Note: The List certificates and Search certificates repository v2 APIs, and the v2 Test a notification endpoint API are deprecated and will be removed on May 1st, 2019. Please upgrade to the next version for each.

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.

Currently only us-south, eu-gb, eu-de and jp-tok are supported.

Note: https://{region}.certificate-manager.bluemix.net/ continues to be supported.

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.bluemix.net/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 CLI (v0.10.0 or above):

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

  • Update operations on certificates are limited to five actions per minute.
  • Testing notification channels is limited to one test per second.
  • Reimporting certificates is limited to five actions per minute.

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, 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.

Notification channel versions

Newly created notification channels are always created with the latest version release.

Slack channel versions

Version 2 (December 2nd, 2018)

  • New notification for reimported certificates.

Version 1

  • Notifications are sent only for expiring certificates.

Callback URL payload versions

Version 3 (January 13th, 2019)

  • Field expiry_date exists only in messages with event type cert_about_to_expire_reimport_required and doesn't exist in messages with other event types.
  • Field expires_on was added to each certificate in array.
{
    "instance_crn": "<INSTANCE_CRN>",
    "certificate_manager_url":"<INSTANCE_DASHBOARD_URL>",
    "event_type": "<EVENT_TYPE>",
    "expiry_date": <EXPIRY_DAY_TIMESTAMP>,
    "certificates":[
          {
             "cert_crn":"<CERTIFICATE_CRN>",
             "name":"<CERTIFICATE_NAME>",
             "domains":"<CERTIFICATE_DOMAIN>",
             "expires_on": <EXPIRY_DAY_TIMESTAMP>,
          },
          ...
     ]     
}

Version 2 (December 2nd, 2018)

  • New notification for reimported certificates.
  • Field name was changed from expiring_certificates to certificates.
  • New field event_type was added. Possible values:
    1. cert_about_to_expire_reimport_required - for certificates that are about to expire in 1,10,30,60,90 days
    2. cert_expired_reimport_required - for certificates that expired today or earlier
    3. cert_reimported - for certificates that were reimported
{
    "instance_crn": "<INSTANCE_CRN>",
    "certificate_manager_url":"<INSTANCE_DASHBOARD_URL>",
    "expiry_date": <EXPIRY_DAY_TIMESTAMP>,
    "event_type": "<EVENT_TYPE>",
    "certificates":[
          {
             "cert_crn":"<CERTIFICATE_CRN>",
             "name":"<CERTIFICATE_NAME>",
             "domains":"<CERTIFICATE_DOMAIN>"
          },
          ...
    ]      
}

Version 1

{
    "instance_crn": "<INSTANCE_CRN>",
    "certificate_manager_url":"<INSTANCE_DASHBOARD_URL>",
    "expiry_date": <EXPIRY_DAY_TIMESTAMP>,
    "expiring_certificates":[
          {
             "cert_crn":"<CERTIFICATE_CRN>",
             "name":"<CERTIFICATE_NAME>",
             "domains":"<CERTIFICATE_DOMAIN>"
          },
          ...
     ]     
}

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, matches 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 document to start with.

    Constraints: matches 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.

List certificates

Retrieves a list of all certificates and their associated metadata.

GET /v2/{instance_id}/certificates
Request

Custom Headers

  • The authorization token.

Path Parameters

  • The CRN-based service instance ID.

    Constraints: length ≥ 4, matches 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: value ≥ 2

  • The first document to start with.

    Constraints: matches 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, matches 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.

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

Custom Headers

  • The authorization token.

Path Parameters

  • The CRN-based service instance ID.

    Constraints: length ≥ 4, matches 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: value ≥ 2

  • The page number.

    Constraints: value ≥ 0

  • A bookmark that was retrieved by a previous search.

  • The first document to start with.

    Constraints: matches 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 certificates repository

Retrieve a list of certificates that is filtered by search parameter. Certificate name, domain or issuer fields will be searched.

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

Custom Headers

  • The authorization token.

Path Parameters

  • The CRN-based service instance ID.

    Constraints: length ≥ 4, matches 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 document to start with.

    Constraints: matches 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, matches 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, matches 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.

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: matches 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: matches 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: matches 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: matches 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

Get 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, matches 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 a new notification channel

Create a new notification channel for the instance.

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

Custom Headers

  • The authorization token.

Path Parameters

  • The CRN-based service instance ID.

    Constraints: length ≥ 4, matches 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, matches 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, matches 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, matches 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 a notification endpoint.

Test a notifications endpoint.

POST /v1/instances/{instance_id}/notifications/channels/test
Request

Custom Headers

  • The authorization token.

Path Parameters

  • The CRN-based service instance ID.

    Constraints: length ≥ 4, matches 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 sent a request to test a notification endpoint.

  • Unexpected error.

No Sample Response

This method does not specify any sample responses.

Test a 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, matches 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

Get the public key for callback notifications.

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

Path Parameters

  • The CRN-based service instance ID.

    Constraints: length ≥ 4, matches 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.