Introduction

The IBM Cloud™ Certificate Manager service provides REST API endpoints to manage SSL certificates and notification channels.

You can test REST endpoints by using Swagger or by running cURL requests in the command line.

API endpoint

https://{region}.certificate-manager.cloud.ibm.com/api

Swagger UI

https://{region}.certificate-manager.cloud.ibm.com/docs

Replace {region} with the prefix that represents the geographic area where your Certificate Manager service instance resides. For more information, see Regions and locations.

Supported regions: us-south, eu-gb, eu-de. jp-tok and au-syd.

Authentication

To work with the API, you must include your IBM Cloud IAM access token and the Certificate Manager instance ID in every request.

You can retrieve an access token by first creating an API key, and then exchanging your API key for an IBM Cloud IAM token. For more information, see Getting an IBM Cloud IAM token by using an API key.

To retrieve your access token:

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -H "Accept: application/json" -d "grant_type=urn%3Aibm%3Aparams%3Aoauth%3Agrant-type%3Aapikey&apikey={API_KEY}" https://iam.cloud.ibm.com/identity/token

Or using CLI:

ibmcloud iam oauth-tokens

Replace {API_KEY} with the API key. Then use the full IAM token value, prefixed by the Bearer token type, to authenticate your API requests.

To retrieve your instance ID, either copy it from the Settings page in the service UI, or using IBM Cloud CLI:

ibmcloud resource service-instance {instance_name} --output JSON

Replace {instance_name} with the unique alias that you assigned to your Certificate Manager instance.

Error handling

The IBM Cloud™ Certificate Manager service uses standard HTTP response codes to indicate indicate if a method completed successfully. A 200 HTTP response always indicates success. HTTP response codes with the format 4xx indicate a failure. A 500 HTTP response code usually indicates an internal system error that cannot be resolved by the user.

Status code summary
Status code Description
200 OK The request was processed successfully.
400 Bad Request The request could not be processed, often due to a missing required parameter.
401 Unauthorized The request could not be processed due to insufficient permissions.
404 Not Found TThe requested resource does not exist.
410 Gone The requested resource was deleted and no longer exists.
412 Disabled The Certificate Manager service instance is disabled.
429 Too Many Requests The request could not be processed due to too many concurrent requests against the API.
500 Server Error Your request could not be processed due to an internal server error. Certificate Manager is currently unavailable.

Rate limiting

  • Creating notifications channels is limited to 5 actions per minute.
  • Updating notifications channels is limited to 5 actions per minute.
  • Testing notifications channels is limited to 1 action per second.
  • Re/importing certificates is limited to 5 actions per minute.
  • Update operations on certificates are limited to 5 actions per minute.
  • Ordering certificates is limited to 5 orders/minute per Certificate Manager instance, 100 orders/hour per IBM user account, and 5 certificates for the same domains per week.
  • Renewing certificates is limited to 5 renews/minute per Certificate Manager instance, 100 renews/hour per IBM user account, and 5 certificates for the same domains per week.

Integration notes

Instance ID and Certificate ID encoding

  • When testing the API using the Swagger UI, there is no need to URL encode the instance ID or certificate ID - Swagger will take care of the URL encoding.
  • When integrating the API in code, or when using the Try It feature in the API Docs, the instance ID and certificate ID must be URL encoded.

Importing certificates from the command line

  • If using curl to import certificates from the command line, you must replace all line breaks in the certificate data with \r\n.

Methods

List certificates

Retrieves a list of all certificates and their associated metadata.

GET /v3/{instance_id}/certificates
Request

Custom Headers

  • The authorization token.

Path Parameters

  • The CRN-based service instance ID.

    Constraints: length ≥ 4, Value must match regular expression ^crn:.+:.+:.+:.+:.+:a\/[0-9a-f]{32}:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\:\:$

Query Parameters

  • The field to sort the certificates by.

    Allowable values: [expires_on,name,domains,issuer,algorithm,key_algorithm,imported,status]

  • The page number.

    Constraints: value ≥ 0

  • The number of certificates per page.

    Constraints: 2 ≤ value ≤ 200

  • The first CRN-based certificate ID to start with.

    Constraints: Value must match regular expression ^crn:.+:.+:.+:.+:.+:a\/[0-9a-f]{32}:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}:certificate:[0-9a-f]{32}$

  • The first value of the field that will be shown in a page, when the list is sorted by field.

Response

Status Code

  • Successfully retrieved a list of all certificates.

  • The service instance ID wasn't found.

  • Unexpected error.

No Sample Response

This method does not specify any sample responses.

Certificates repository metadata

Retrieves metadata of the certificates repository. The total number of certificates, the number of expired certificates, and the number of certificates expiring in the next 30 days.

GET /v2/{instance_id}/certificates/metadata
Request

Custom Headers

  • The authorization token.

Path Parameters

  • The CRN-based service instance ID.

    Constraints: length ≥ 4, Value must match regular expression ^crn:.+:.+:.+:.+:.+:a\/[0-9a-f]{32}:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\:\:$

Response

Status Code

  • Metadata of the list of certificates.

  • The service instance ID wasn't found.

  • Unexpected error.

No Sample Response

This method does not specify any sample responses.

Search certificates repository

Retrieve a list of certificates that is filtered by search parameter. Certificate name, domain or issuer fields will be searched. To search for an exact value, enclose your search term with double-quotes.

GET /v3/{instance_id}/certificates/search
Request

Custom Headers

  • The authorization token.

Path Parameters

  • The CRN-based service instance ID.

    Constraints: length ≥ 4, Value must match regular expression ^crn:.+:.+:.+:.+:.+:a\/[0-9a-f]{32}:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\:\:$

Query Parameters

  • The field to sort the certificates by.

    Allowable values: [expires_on,name,domains,issuer,algorithm,key_algorithm,imported,status]

  • The search string.

    Constraints: length ≤ 250

  • The number of certificates per page.

    Constraints: 2 ≤ value ≤ 200

  • The page number.

    Constraints: value ≥ 0

  • A bookmark that was retrieved by a previous search.

  • The first CRN-based certificate ID to start with.

    Constraints: Value must match regular expression ^crn:.+:.+:.+:.+:.+:a\/[0-9a-f]{32}:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}:certificate:[0-9a-f]{32}$

Response

Status Code

  • Successfully retrieved a list of search results of the certificate.

  • The service instance ID wasn't found.

  • Unexpected error.

No Sample Response

This method does not specify any sample responses.

Search results metadata

Retrieves metadata of the search results. The total number of certificates, the number of expired certificates, and the number of certificates expiring in the next 30 days that match the search term.

GET /v2/{instance_id}/certificates/search/metadata
Request

Custom Headers

  • The authorization token.

Path Parameters

  • The CRN-based service instance ID.

    Constraints: length ≥ 4, Value must match regular expression ^crn:.+:.+:.+:.+:.+:a\/[0-9a-f]{32}:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\:\:$

Query Parameters

  • The search string.

    Constraints: length ≤ 250

Response

Status Code

  • Successfully retreieved metadata of the list of certificates.

  • The service instance ID wasn't found.

  • Unexpected error.

No Sample Response

This method does not specify any sample responses.

Import a certificate

Import a certificate in Privacy-enhanced Electronic Mail (PEM) format with its private key. You can also import an intermediate certificate.

POST /v3/{instance_id}/certificates/import
Request

Custom Headers

  • The authorization token.

Path Parameters

  • The CRN-based service instance ID.

    Constraints: length ≥ 4, Value must match regular expression ^crn:.+:.+:.+:.+:.+:a\/[0-9a-f]{32}:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\:\:$

The certificate data.

Response

Status Code

  • Successfully imported the certificate.

  • Unexpected error.

No Sample Response

This method does not specify any sample responses.

Order a certificate

Request to order a certificate.

POST /v1/{instance_id}/certificates/order
Request

Custom Headers

  • The authorization token.

Path Parameters

  • The CRN-based service instance ID.

    Constraints: length ≥ 4, Value must match regular expression ^crn:.+:.+:.+:.+:.+:a\/[0-9a-f]{32}:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\:\:$

Certificate order data.

Response

Status Code

  • OK.

  • Unexpected error.

No Sample Response

This method does not specify any sample responses.

Renew a certificate

Request to renew a certificate.

POST /v1/certificate/{certificate_id}/renew
Request

Custom Headers

  • The authorization token.

Path Parameters

  • The CRN-based certificate ID.

    Constraints: Value must match regular expression ^crn:.+:.+:.+:.+:.+:a\/[0-9a-f]{32}:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}:certificate:[0-9a-f]{32}$

Certificate renew data.

Response

Status Code

  • OK.

  • Unexpected error.

No Sample Response

This method does not specify any sample responses.

Get certificate metadata

Request to get a service instance certificate metadata.

GET /v1/certificate/{certificate_id}/metadata
Request

Custom Headers

  • The authorization token.

Path Parameters

  • The CRN-based certificate ID.

    Constraints: Value must match regular expression ^crn:.+:.+:.+:.+:.+:a\/[0-9a-f]{32}:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}:certificate:[0-9a-f]{32}$

Response

Status Code

  • Retrieve the metadata of a certificate.

  • Certificate is not found.

  • Unexpected error.

No Sample Response

This method does not specify any sample responses.

Get a certificate

Retrieve the certificate, its private key, and its intermediate certificate if present. If this is a reimported certificate, you can get the previous version using the query param version=previous.

GET /v2/certificate/{certificate_id}
Request

Custom Headers

  • The authorization token.

Path Parameters

  • The CRN-based certificate ID.

    Constraints: Value must match regular expression ^crn:.+:.+:.+:.+:.+:a\/[0-9a-f]{32}:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}:certificate:[0-9a-f]{32}$

Query Parameters

  • Select previous to download the previously imported certificate, its private key and its intermediate certificate if present.

    Allowable values: [previous]

Response

Status Code

  • Successfully retrieved the certificate data.

  • The certificate wasn't found.

  • Unexpected error.

No Sample Response

This method does not specify any sample responses.

Delete a certificate

Delete the requested certificate.

DELETE /v2/certificate/{certificate_id}
Request

Custom Headers

  • The authorization token.

Path Parameters

  • The CRN-based certificate ID.

    Constraints: Value must match regular expression ^crn:.+:.+:.+:.+:.+:a\/[0-9a-f]{32}:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}:certificate:[0-9a-f]{32}$

Response

Status Code

  • Successfully deleted the requested certificate.

  • The certificate couldn't be found.

  • Unexpected error.

No Sample Response

This method does not specify any sample responses.

Update a certificate's metadata

Update a certificate's name and description.

POST /v3/certificate/{certificate_id}
Request

Custom Headers

  • The authorization token.

Path Parameters

  • The CRN-based certificate ID.

    Constraints: Value must match regular expression ^crn:.+:.+:.+:.+:.+:a\/[0-9a-f]{32}:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}:certificate:[0-9a-f]{32}$

Update the data for a certificate.

Response

Status Code

  • Successfully updated the certificate.

  • The certificate wasn't found.

  • Too many requests.

  • Unexpected error.

No Sample Response

This method does not specify any sample responses.

Reimport a certificate

Reimport a certificate. The reimported certificate's domain(s) must match the current certificate's domain(s).

PUT /v1/certificate/{certificate_id}
Request

Custom Headers

  • The authorization token.

Path Parameters

  • The CRN-based certificate ID.

    Constraints: Value must match regular expression ^crn:.+:.+:.+:.+:.+:a\/[0-9a-f]{32}:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}:certificate:[0-9a-f]{32}$

Reimport data for a certificate.

Response

Status Code

  • Successfully reimported the certificate.

  • The certificate wasn't found.

  • Too many requests.

  • Unexpected error.

No Sample Response

This method does not specify any sample responses.

Get all notification channels

Retrieve all notification channels of the instance.

GET /v1/instances/{instance_id}/notifications/channels
Request

Custom Headers

  • The authorization token.

Path Parameters

  • The CRN-based service instance ID.

    Constraints: length ≥ 4, Value must match regular expression ^crn:.+:.+:.+:.+:.+:a\/[0-9a-f]{32}:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\:\:$

Response

The list of notification channels.

Status Code

  • Successfully retrieved a list of all notification channels.

  • Unexpected error.

No Sample Response

This method does not specify any sample responses.

Create notification channel

Create a new notification channel.

PUT /v1/instances/{instance_id}/notifications/channels
Request

Custom Headers

  • The authorization token.

Path Parameters

  • The CRN-based service instance ID.

    Constraints: length ≥ 4, Value must match regular expression ^crn:.+:.+:.+:.+:.+:a\/[0-9a-f]{32}:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\:\:$

Response

Status Code

  • Successfully created a new notifications channel.

  • Unexpected error.

No Sample Response

This method does not specify any sample responses.

Update notification channel state

Update a notification channel's state.

PUT /v1/instances/{instance_id}/notifications/{channel_id}/state
Request

Custom Headers

  • The authorization token.

Path Parameters

  • The CRN-based service instance ID.

    Constraints: length ≥ 4, Value must match regular expression ^crn:.+:.+:.+:.+:.+:a\/[0-9a-f]{32}:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\:\:$

  • Channel ID

Response

Status Code

  • Successfully updated the notifications channel state.

  • Unexpected error.

No Sample Response

This method does not specify any sample responses.

Update notification channel

Update a notification channel endpoint.

POST /v1/instances/{instance_id}/notifications/{channel_id}
Request

Custom Headers

  • The authorization token.

Path Parameters

  • The CRN-based service instance ID.

    Constraints: length ≥ 4, Value must match regular expression ^crn:.+:.+:.+:.+:.+:a\/[0-9a-f]{32}:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\:\:$

  • Channel ID

Response

Status Code

  • Successfully updated the notification channel endpoint.

  • Unexpected error.

No Sample Response

This method does not specify any sample responses.

Delete notification channel

Delete a notification channel.

DELETE /v1/instances/{instance_id}/notifications/{channel_id}
Request

Custom Headers

  • The authorization token.

Path Parameters

  • The CRN-based service instance ID.

    Constraints: length ≥ 4, Value must match regular expression ^crn:.+:.+:.+:.+:.+:a\/[0-9a-f]{32}:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\:\:$

  • Channel ID

Response

Status Code

  • Successfully deleted the notification channel.

  • Unexpected error.

No Sample Response

This method does not specify any sample responses.

Test notification channel

Test a notifications channel.

GET /v1/instances/{instance_id}/notifications/{channel_id}/test
Request

Custom Headers

  • The authorization token.

Path Parameters

  • The CRN-based service instance ID.

    Constraints: length ≥ 4, Value must match regular expression ^crn:.+:.+:.+:.+:.+:a\/[0-9a-f]{32}:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\:\:$

  • Channel ID

Response

Status Code

  • Successfully sent a request to test a notification channel.

  • Unexpected error.

No Sample Response

This method does not specify any sample responses.

Get notifications public key

Retrieve the public key for Callback URL notifications.

GET /v1/instances/{instance_id}/notifications/publickey
Request

Path Parameters

  • The CRN-based service instance ID.

    Constraints: length ≥ 4, Value must match regular expression ^crn:.+:.+:.+:.+:.+:a\/[0-9a-f]{32}:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\:\:$

Query Parameters

  • The format of the required key.

    Allowable values: [jwk,pem]

    Default: jwk

Response

Status Code

  • Successfully retreived the notifications public key.

  • Resource not found.

  • Instance is disabled.

  • Unexpected error.

No Sample Response

This method does not specify any sample responses.