SIsilverflow
API Keys

Add API Key certificate [EXPERIMENTAL]

This operation binds a client certificate to the API Key. The certificate must be trusted by one of the Agent's Trust Anchors, either because a Trust Anchor issued it, or through the intermediate certificates sent with the request. A certificate that is itself a Trust Anchor is accepted as well. The response contains the certificateKey of the certificate, which identifies it when you archive it.

An API Key can have at most two active certificates. The limit exists so that a certificate can be rotated without downtime: add the new certificate, test it, then archive the old one. If two certificates are already active, archive one before adding another. A certificate that was archived can be added again.

Adding a certificate does not enable mTLS. To do that, update the API Key with mtlsEnabled. If mTLS is already enabled, the certificate can be used once the change has propagated. Changes to certificates, Trust Anchors and mTLS settings take a short time to take effect, so allow for a delay before you rely on them.

Requires apiKeys:Update permission.

post/apiKeys/{apiKey}/certificates

Request

Path parameters

apiKeystring required

Uniquely identifies an API Key

Example:apk-1UF2NafdfrdPMf2XrS2

Uniquely identifies an API Key.

Request body

certificatestring required

A single PEM-encoded X.509 client certificate, including the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines. It must be valid now, must not be allowed to sign certificates (keyCertSign), and must be trusted by one of the Agent's Trust Anchors.

intermediatesstring[]

PEM-encoded intermediate certificates, ordered from the issuer of the client certificate up towards the Trust Anchor. Only needed when the Trust Anchor did not sign the client certificate directly. They are used to validate the chain and are not stored.

descriptionstring

Example request

{
  "certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n",
  "intermediates": [
    "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n"
  ],
  "description": "Production client certificate, rotated 2026-06-01"
}

Response

The added certificate

certificateKeystring required

Uniquely identifies a certificate bound to an API Key

fingerprintstring required

The SHA-256 hash of the DER-encoded certificate, as URL-safe base64 with padding (44 characters, using - and _, ending in =). This is the value of the CloudFront-Viewer-Cert-Sha256 header for the certificate. To compute it from a certificate file: openssl x509 -in cert.pem -outform der | openssl dgst -sha256 -binary | openssl base64 -A | tr '+/' '-_'.

notBeforestring date-time required

The start of the certificate's validity period, taken from the certificate

notAfterstring date-time required

The end of the certificate's validity period, taken from the certificate

descriptionstring
createdstring date-time required

The date and time this object was created

trustAnchorFingerprintstring required

The SHA-256 hash of the DER-encoded certificate, as URL-safe base64 with padding (44 characters, using - and _, ending in =). This is the value of the CloudFront-Viewer-Cert-Sha256 header for the certificate. To compute it from a certificate file: openssl x509 -in cert.pem -outform der | openssl dgst -sha256 -binary | openssl base64 -A | tr '+/' '-_'.

status'active' | 'archived' required

The status of the certificate. Archived certificates stay in the list.

Example response

{
  "certificateKey": "crt-602nkAxGfhDN8yQBibpx",
  "fingerprint": "LYHqA-dGPaCqZfnoqB6EQ9-Agm8IjZy9LcTj376z8n4=",
  "trustAnchorFingerprint": "LYHqA-dGPaCqZfnoqB6EQ9-Agm8IjZy9LcTj376z8n4="
}

Changes

No recorded changes to this operation across all 1 revision of this API.