Download OpenAPI specification:Download
The CA Gateway API is a RESTful Web service API that provides a range of certificate issuance and management functions. The API fronts multiple issuing Certification Authorities (CAs) and accommodates a range of public key algorithms, request/response formats, and certificate contents. A suitable authenticated client of the API can:
The following terms are used throughout the documentation and the API.
Issuing Certification Authority: The CA that signs certificates and revocation lists. Each CA has a unique identifying name within the API.
Root Certification Authority: The trust anchor CA that forms the root of trust. The root CA may be the same CA as the issuing CA, or it may be a separate superior CA. If the root CA is the same CA as the issuing CA, the issuing CA's certificate will be self-signed. A trust chain is formed from the series of certificates from the issued certificate up to the root CA's self-signed certificate.
Certificate Revocation List (CRL): A list of certificate serial numbers signed by the issuing CA. The list is formed from certificates that are no longer trusted by the CA, either temporarily through suspension (certificate hold) or permanently through revocation. New CRLs containing the updated list are issued frequently for distribution to relying parties.
Certificate Profile: An object available through the API that describes a particular type of certificate intended for a particular purpose. For example, a device authentication certificate profile defines a certificate for authenticating devices over a network. For another example, an S/MIME email encryption certificate profile defines a certificate for encrypting email messages. Certificate requests are associated with the desired certificate profile, and the certificate returned will reflect the purpose defined by the certificate profile. Each Certificate Profile contains information that must be provided by the client in the certificate request, such as naming information. Each Certificate Profile also specifies information used to generate the certificate, such as algorithms, key lengths, policy, and so on. Each Certificate Profile has a unique identifying name within the API.
Subject Distinguished Name: The name in certificates that identifies the owner or holder of the certificate. For example, "cn=John Doe, ou=Issuing CA, o=Example, c=US".
Issuer Distinguished Name: The name in certificates that identifies the issuing CA. For example, "ou=Issuing CA, o=Example, c=US".
Subject Alternative Name: A list of alternative names for the end entity certificate owner which are also to be contained within the certificate. There may be several Subject Alternative Names depending on the type of certificate, and they reflect the application or purpose of the certificate. For example, Subject Alternative Names can include Email addresses (RFC 822 addresses), DNS Names, IP Addresses, and so on.
Certificate Request (PKCS #10 CSR): When requesting a certificate using a profile that specifies that the key pair should be generated by the client, then the public key is submitted to the API in PKCS #10 CSR format. The CSR should be signed by the private key in order to prove that the client is in possession of the private key.
CA Identifiers used in the URI of a request must be encoded in UTF8 and percent encoded.
Certificate issuer and subject identities are represented by distinguished names (DNs), as specified in the X.500 standard. For example: "ou=Issuing CA, o=Example, c=US". Subject DNs are supplied to the API as strings, and any Subject DNs containing non-alphanumeric characters or punctuation must be encoded according to RFC 2253 (https://tools.ietf.org/html/rfc2253). These characters can be escaped by enclosing them within double quotes, for example:
The following characters are supported in a Subject Distinguished Name by the CA Gateway but must be RFC2253 encoded:
When a certificate's serial number is used in an URI, the serial number must:
Use Case: Submitting a CSR containing the public key to be certified.
When the keys and certificate are intended to be used for authentication or signing alone, then the key pair will most commonly be generated at the client. Generating the key pair at the client provides a stronger binding between the certificate and the certificate owner. For example, a network device will generate a key pair and certificate request before becoming operational. For another example, a Web server that requires a certificate for its TLS endpoint will generate its own key pair and certificate request.
The sequence of events is typically as follows:
During the above process, the private key never leaves the device. This enhances nonrepudiation.
Step 2 above can be accomplished over the CA Gateway API with the following sequence of API calls:
In the current release, all certificates will be issued synchronously.
Use Case: Requesting S/MIME certificate in PKCS #12 format for email encryption
An S/MIME certificate will typically be dual-usage so it can be used for both email signing/verification and encryption/decryption. For business continuity reasons, the Certificate Profile for an S/MIME certificate will specify that the private key will be backed up by the CA. Backing up the private key allows subsequent recovery of the private key in case it is ever lost.
The sequence of events is typically as follows:
The steps above can be accomplished over the CA Gateway API in the following sequence of API calls:
In the current release, all certificates will be issued synchronously.
Returns general information about this installation of the CA Gateway. You can use this query to ping the gateway or get the number of available CAs.
correlationId | string A free-form identifier that will be logged with this query if any logging occurs. |
OK.
Something was wrong with the request.
Unauthorized.
The specified resource was not found.
An internal error occurred on the gateway.
Operation is not implemented in this gateway.
{- "type": "InfoResponse",
- "message": {
- "code": "string",
- "message": "string",
- "target": "string",
- "value": "string",
- "details": [
- {
- "code": "string",
- "message": "string",
- "target": "string",
- "value": "string",
- "property1": "string",
- "property2": "string"
}
], - "property1": "string",
- "property2": "string"
}, - "information": {
- "version": "string",
- "product": "string",
- "specificationVersion": "string",
- "configuredCACount": 0,
- "timestamp": "2023-01-11T17:19:11Z"
}
}
Lists the CAs available through this gateway. The list will include only the CAs that the API user has permissions to use.
$fields | string The $fields parameter allows you to specify which fields to return. Currently, only the following extra fields can be requested:
None of these fields are returned by default. All other fields are returned by default. |
correlationId | string A free-form identifier that will be logged with this query if any logging occurs. |
OK.
Something was wrong with the request.
Unauthorized.
The specified resource was not found.
An internal error occurred on the gateway.
Operation is not implemented in this gateway.
{- "type": "CAListResponse",
- "message": {
- "code": "string",
- "message": "string",
- "target": "string",
- "value": "string",
- "details": [
- {
- "code": "string",
- "message": "string",
- "target": "string",
- "value": "string",
- "property1": "string",
- "property2": "string"
}
], - "property1": "string",
- "property2": "string"
}, - "metadata": {
- "currentCount": 0,
- "totalCount": 0,
- "currentOffset": 0,
- "currentLimit": 0
}, - "caList": [
- {
- "id": "string",
- "name": "string",
- "description": "string",
- "status": "string",
- "properties": {
- "property1": "string",
- "property2": "string"
}, - "certificate": {
- "status": "normal",
- "versionNumber": "string",
- "serialNumber": "string",
- "signatureAlgID": "string",
- "issuerName": "string",
- "validityPeriod": "string",
- "subjectName": "string",
- "rfc2253EncodedSubjectName": "string",
- "rfc2253EscapedSubjectName": "string",
- "subjectPublicKeyInfo": {
- "publicKeyAlg": "string",
- "subjectPublicKey": "string"
}, - "issuerUniqueIdentifier": "string",
- "subjectUniqueIdentifier": "string",
- "certificateSignatureAlg": "string",
- "revocationInfo": {
- "comment": "string",
- "compromiseDate": "2023-01-11T17:19:11Z",
- "revocationDate": "2023-01-11T17:19:11Z",
- "reason": "unspecified"
}, - "certificateData": "string",
- "properties": {
- "property1": "string",
- "property2": "string"
}
}, - "chain": [
- {
- "status": "normal",
- "versionNumber": "string",
- "serialNumber": "string",
- "signatureAlgID": "string",
- "issuerName": "string",
- "validityPeriod": "string",
- "subjectName": "string",
- "rfc2253EncodedSubjectName": "string",
- "rfc2253EscapedSubjectName": "string",
- "subjectPublicKeyInfo": {
- "publicKeyAlg": "string",
- "subjectPublicKey": "string"
}, - "issuerUniqueIdentifier": "string",
- "subjectUniqueIdentifier": "string",
- "certificateSignatureAlg": "string",
- "revocationInfo": {
- "comment": "string",
- "compromiseDate": "2023-01-11T17:19:11Z",
- "revocationDate": "2023-01-11T17:19:11Z",
- "reason": "unspecified"
}, - "certificateData": "string",
- "properties": {
- "property1": "string",
- "property2": "string"
}
}
], - "licenseInfo": [
- {
- "property1": "string",
- "property2": "string"
}
]
}
]
}
Detailed information about a CA can be requested, such as:
caId required | string Example: CA-1001 ID of the CA. This is a free-form string that is configured with the CA configuration and returned by GET /v1/certificate-authorities. |
$fields | string The $fields parameter allows you to specify which fields to return. Currently, only the following extra fields can be requested:
None of these fields are returned by default. All other fields are returned by default. |
correlationId | string A free-form identifier that will be logged with this query if any logging occurs. |
OK.
Something was wrong with the request.
Unauthorized.
The specified resource was not found.
An internal error occurred on the gateway.
Operation is not implemented in this gateway.
{- "type": "CAResponse",
- "message": {
- "code": "string",
- "message": "string",
- "target": "string",
- "value": "string",
- "details": [
- {
- "code": "string",
- "message": "string",
- "target": "string",
- "value": "string",
- "property1": "string",
- "property2": "string"
}
], - "property1": "string",
- "property2": "string"
}, - "ca": {
- "id": "string",
- "name": "string",
- "description": "string",
- "status": "string",
- "properties": {
- "property1": "string",
- "property2": "string"
}, - "certificate": {
- "status": "normal",
- "versionNumber": "string",
- "serialNumber": "string",
- "signatureAlgID": "string",
- "issuerName": "string",
- "validityPeriod": "string",
- "subjectName": "string",
- "rfc2253EncodedSubjectName": "string",
- "rfc2253EscapedSubjectName": "string",
- "subjectPublicKeyInfo": {
- "publicKeyAlg": "string",
- "subjectPublicKey": "string"
}, - "issuerUniqueIdentifier": "string",
- "subjectUniqueIdentifier": "string",
- "certificateSignatureAlg": "string",
- "revocationInfo": {
- "comment": "string",
- "compromiseDate": "2023-01-11T17:19:11Z",
- "revocationDate": "2023-01-11T17:19:11Z",
- "reason": "unspecified"
}, - "certificateData": "string",
- "properties": {
- "property1": "string",
- "property2": "string"
}
}, - "chain": [
- {
- "status": "normal",
- "versionNumber": "string",
- "serialNumber": "string",
- "signatureAlgID": "string",
- "issuerName": "string",
- "validityPeriod": "string",
- "subjectName": "string",
- "rfc2253EncodedSubjectName": "string",
- "rfc2253EscapedSubjectName": "string",
- "subjectPublicKeyInfo": {
- "publicKeyAlg": "string",
- "subjectPublicKey": "string"
}, - "issuerUniqueIdentifier": "string",
- "subjectUniqueIdentifier": "string",
- "certificateSignatureAlg": "string",
- "revocationInfo": {
- "comment": "string",
- "compromiseDate": "2023-01-11T17:19:11Z",
- "revocationDate": "2023-01-11T17:19:11Z",
- "reason": "unspecified"
}, - "certificateData": "string",
- "properties": {
- "property1": "string",
- "property2": "string"
}
}
], - "licenseInfo": [
- {
- "property1": "string",
- "property2": "string"
}
]
}
}
Returns a list of capabilities that a CA supports. Capabilities determine which API calls, parameter values, and features that a particular CA supports.
The capabilities will be grouped into different categories. The full name of a capability shall be the category name, a dot, and the capability name.
caId required | string Example: CA-1001 ID of the CA. This is a free-form string that is configured with the CA configuration and returned by GET /v1/certificate-authorities. |
correlationId | string A free-form identifier that will be logged with this query if any logging occurs. |
OK.
Something was wrong with the request.
Unauthorized.
The spe