Certificate Manager에서는 인증서 목록 조회, 다운로드, 인증서 파일 교체를 위한 API를 제공합니다. 클라이언트는 콘솔에서 인증서와 인증서 파일을 등록한 후 API로 데이터를 사용할 수 있습니다.
https://certmanager.api.nhncloudservice.com
CertificateManager는 API 호출 시 인증/인가를 위해 User Access Key 토큰을 사용합니다. User Access Key 토큰은 User Access Key를 기반으로 발급되는 Bearer 타입의 일시적 액세스 토큰입니다. User Access Key 토큰 발급 및 사용에 대한 자세한 내용은 User Access Key 토큰을 참고하세요.
CertificateManager API는 역할 기반 접근 제어(RBAC)를 사용하고 있습니다.
사용자는 API 사용을 위해 CertificateManager ADMIN 역할 또는 CertificateManager VIEWER 역할 소유해야합니다.
단, 인증서 파일 교체 API는 Certificate Manager ADMIN 역할이 있어야 사용할 수 있습니다.
| 메서드 | URI | 설명 |
|---|---|---|
| GET | /certmanager/v1.3/appkeys/{appKey}/certificates | 인증서 목록을 조회합니다. |
| GET | /certmanager/v1.3/appkeys/{appKey}/certificates/{certificateName}/files | 등록된 인증서 파일을 인증서 이름으로 다운로드합니다. |
| GET | /certmanager/v1.3/appkeys/{appKey}/certificates/{certificateId}/certificate-files | 등록된 인증서 파일을 인증서 ID로 다운로드합니다. |
| PUT | /certmanager/v1.3/appkeys/{appKey}/certificates/{certificateName}/files | 등록된 인증서의 인증서 파일을 교체합니다. |
| 값 | 타입 | 설명 |
|---|---|---|
| appKey | String | 사용할 데이터를 저장하고 있는 NHN Cloud 프로젝트의 앱키 |
| certificateName | String | 사용할 데이터(인증서) 이름 |
| certificateId | Number | 사용할 데이터(인증서) ID |
{
"header": {
"resultCode": 0,
"resultMessage": "success",
"isSuccessful": true
},
"body": {
}
}
| 값 | 타입 | 설명 |
|---|---|---|
| resultCode | Number | API 호출 결과 코드값 |
| resultMessage | String | API 호출 결과 메시지 |
| isSuccessful | Boolean | API 호출 성공 여부 |
Certificate Manager에 등록한 인증서 목록을 조회할 때 사용합니다.
GET https://certmanager.api.nhncloudservice.com/certmanager/v1.3/appkeys/{appKey}/certificates?pageSize={pageSize}&pageNum={pageNum}&all={all}&status={status}
| 값 | 타입 | 설명 | 입력 가능 |
|---|---|---|---|
| pageSize | Number | 페이지 크기 | 10(기본값) |
| pageNum | Number | 페이지 번호 | 1(기본값) |
| all | Boolean | 전체 조회 여부 | true, false(기본값) |
| status | String | 인증서 상태 | ALL, EXPIRED, UNEXPIRED(기본값) |
※ all, status의 값은 대소문자 구분 없이 사용할 수 있습니다.
[Response Header]
Content-Type:application/json
[Response Body]
{
"header": {
"resultCode": 0,
"resultMessage": "success",
"isSuccessful": true
},
"body": {
"totalCount": 1,
"totalPage": 1,
"currentPage": 1,
"pageSize": 10,
"data": [
{
"certificateId": 1,
"certificateName": "nhncloudservice.com",
"authority": "NHN",
"domains": [
"nhncloudservice.com",
"*.nhncloudservice.com"
],
"signatureAlgorithm": "SHA256withRSA",
"fileCreationDate": "2025-03-02",
"expirationDate": "2026-03-25"
}
]
}
}
| 값 | 타입 | 설명 |
|---|---|---|
| totalCount | Number | 전체 인증서 수 |
| totalPage | Number | 전체 페이지 수 |
| currentPage | Number | 현재 페이지 |
| pageSize | Number | 페이지 크기 |
| certificateId | Number | 인증서 ID |
| certificateName | String | 인증서 이름 |
| authority | String | 인증 기관 |
| signatureAlgorithm | String | 서명 방식 |
| fileCreationDate | String | 인증서 파일 생성일 |
| expirationDate | String | 인증서 파일 만료일 |
Certificate Manager에 등록한 인증서 파일을 인증서 이름으로 다운로드할 때 사용합니다.
GET https://certmanager.api.nhncloudservice.com/certmanager/v1.3/appkeys/{appKey}/certificates/{certificateName}/files
[Response Header]
Content-Disposition:attachment; filename="{파일명}"
Content-Type:application/octet-stream
[Response Body]
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
...
-----BEGIN RSA PRIVATE KEY-----
...
-----END RSA PRIVATE KEY-----
[Response Header]
Content-Type:application/json
[Response Body]
{
"header": {
"resultCode": 52000,
"resultMessage": "Certificate name does not exist.",
"isSuccessful": false
},
"body": {}
}
인증서 파일 다운로드 API는 curl 명령어를 사용해 요청할 수 있습니다.
#파일에 쓰기
curl 'https://certmanager.api.nhncloudservice.com/certmanager/v1.3/appkeys/{appKey}/certificates/{certificateName}/files' \
-H "X-NHN-AUTHORIZATION: Bearer {발급 받은 토큰}" > cert.pem
#파일명 지정
curl -o cert.pem 'https://certmanager.api.nhncloudservice.com/certmanager/v1.3/appkeys/{appKey}/certificates/{certificateName}/files' \
-H "X-NHN-AUTHORIZATION: Bearer {발급 받은 토큰}"
#업로드한 파일명 유지
curl -OJ 'https://certmanager.api.nhncloudservice.com/certmanager/v1.3/appkeys/{appKey}/certificates/{certificateName}/files' \
-H "X-NHN-AUTHORIZATION: Bearer {발급 받은 토큰}"
* 기타 curl 명령어 사용법은 아래 가이드를 참고하세요.
* curl command guide: https://curl.haxx.se/docs/manpage.html
Certificate Manager에 등록한 인증서 파일을 인증서 ID로 다운로드할 때 사용합니다. 인증서 ID는 인증서 목록 조회 API 응답의 certificateId 값입니다.
GET https://certmanager.api.nhncloudservice.com/certmanager/v1.3/appkeys/{appKey}/certificates/{certificateId}/certificate-files
[Response Header]
Content-Disposition:attachment; filename="{파일명}"
Content-Type:application/octet-stream
[Response Body]
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
...
-----BEGIN RSA PRIVATE KEY-----
...
-----END RSA PRIVATE KEY-----
[Response Header]
Content-Type:application/json
[Response Body]
{
"header": {
"resultCode": 52009,
"resultMessage": "Certificate id does not exist.",
"isSuccessful": false
},
"body": {}
}
※ 실패 응답은 HTTP 상태 코드 404(Not Found)와 함께 반환됩니다.
Certificate Manager에 등록한 인증서의 인증서 파일을 새 파일로 교체할 때 사용합니다. 인증서를 갱신한 뒤 갱신된 인증서 파일을 반영하는 용도로 사용할 수 있습니다.
PUT https://certmanager.api.nhncloudservice.com/certmanager/v1.3/appkeys/{appKey}/certificates/{certificateName}/files
[Request Header]
Content-Type:multipart/form-data
[Request Body]
| 값 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
| certificateFile | File | Y | 교체할 인증서 파일 확장자가 .pem인 파일만 업로드할 수 있으며, 최대 크기는 512KB입니다. |
| passphrase | String | N | 인증서 파일에 포함된 개인 키의 패스프레이즈 입력하지 않으면 기존에 등록된 패스프레이즈가 유지됩니다. 패스프레이즈를 삭제하려면 콘솔에서 인증서를 수정하세요. |
[Response Header]
Content-Type:application/json
[Response Body]
{
"header": {
"resultCode": 0,
"resultMessage": "success",
"isSuccessful": true
},
"body": {
"certificateId": 1,
"certificateName": "nhncloudservice.com",
"previousExpirationDate": "2026-03-25",
"expirationDate": "2027-03-25",
"domains": [
"nhncloudservice.com",
"*.nhncloudservice.com"
]
}
}
| 값 | 타입 | 설명 |
|---|---|---|
| certificateId | Number | 인증서 ID |
| certificateName | String | 인증서 이름 |
| previousExpirationDate | String | 교체 전 인증서 파일 만료일 |
| expirationDate | String | 교체한 인증서 파일 만료일 |
| domains | List | 인증서의 도메인 목록[CN(CommonName) + SAN(SubjectAlternativeNames)] |
[Response Header]
Content-Type:application/json
[Response Body]
{
"header": {
"resultCode": 52010,
"resultMessage": "Certificate expires in less than 15 days.",
"isSuccessful": false
},
"body": {}
}
※ 실패 응답은 HTTP 상태 코드 200(OK)과 함께 반환됩니다. 처리 결과는 header의 isSuccessful, resultCode 값으로 확인하세요.
인증서 파일 교체 API는 curl 명령어를 사용해 요청할 수 있습니다. -F 옵션을 사용하면 Content-Type 헤더가 multipart/form-data로 자동 설정됩니다.
#인증서 파일 교체
curl -X PUT 'https://certmanager.api.nhncloudservice.com/certmanager/v1.3/appkeys/{appKey}/certificates/{certificateName}/files' \
-H "X-NHN-AUTHORIZATION: Bearer {발급 받은 토큰}" \
-F 'certificateFile=@cert.pem'
#패스프레이즈와 함께 교체
curl -X PUT 'https://certmanager.api.nhncloudservice.com/certmanager/v1.3/appkeys/{appKey}/certificates/{certificateName}/files' \
-H "X-NHN-AUTHORIZATION: Bearer {발급 받은 토큰}" \
-F 'certificateFile=@cert.pem' \
-F 'passphrase={패스프레이즈}'
* 업로드하는 파일의 이름은 확장자가 .pem이어야 합니다. 로컬 파일의 확장자가 다르면 -F 'certificateFile=@cert.crt;filename=cert.pem'과 같이 파일명을 지정하세요.
| isSuccessful | resultCode | resultMessage | 설명 |
|---|---|---|---|
| true | 0 | SUCCESS | 성공 |
| false | 40000 | 'certificateFile' is required | 요청에 인증서 파일(certificateFile)이 없습니다. |
| false | 52000 | Certificate name does not exist. | 요청한 인증서 이름이 존재하지 않습니다. |
| false | 52001 | Certificate file does not exist. | 요청한 인증서 파일이 존재하지 않습니다. |
| false | 52002 | There are more than one certificate file. | 요청한 인증서에 등록된 파일이 두 개 이상입니다. |
| false | 52003 | The certificate file is not a pem file. | 요청한 인증서 파일이 PEM 형식 파일이 아닙니다. |
| false | 52004 | The certificate name in the file is different from the requested certificate name. | 요청한 인증서 이름과 인증서 파일에 등록된 이름이 다릅니다. |
| false | 52005 | Certificate file has expired | 요청한 인증서 파일이 만료된 파일입니다. |
| false | 52006 | The certificate has an invalid certificate authority name. | 요청한 인증서 파일의 인증 기관 정보가 유효하지 않습니다. |
| false | 52007 | Requested certificate file should be one. | 동시에 하나의 인증서 파일만 업로드 가능합니다. |
| false | 52008 | Maximum permitted size is {} bytes. But, requested {} bytes. | 업로드 가능한 최대 파일 크기는 512KB입니다. |
| false | 52009 | Certificate id does not exist. | 요청한 인증서 ID가 존재하지 않습니다. |
| false | 52010 | Certificate expires in less than {} days. | 요청한 인증서 파일의 잔여 유효 기간이 15일 미만입니다. |
| false | 60005 | certificate domains information is different from existing | 요청한 인증서 파일의 도메인(CN, SAN) 구성이 등록된 인증서와 다릅니다. |
| false | 62001 | invalid certificate file | 요청한 인증서 파일의 형식이 올바르지 않습니다. |