---
title: "Add API Key certificate [EXPERIMENTAL]"
method: POST
path: "/apiKeys/{apiKey}/certificates"
tags: ["API Keys"]
---

# Add API Key certificate \[EXPERIMENTAL\]

`POST /apiKeys/{apiKey}/certificates`

## Request

- Base URL: `https://eu-west-1.api.silverflow.com/v1`
- URL: `https://eu-west-1.api.silverflow.com/v1/apiKeys/{apiKey}/certificates`
- Auth: one of:
  - HTTP basic
  - HTTP bearer
- TypeScript: <https://skmtc.dev/silverflow/apis/silverflow-api/docs/apiKeys/:apiKey/certificates/post.ts> (a function with typed inputs; its response is checked against the schema)

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.

## Path parameters

- `apiKey` string, required: Uniquely identifies an API Key

## Request body

- ApiKeyCertificateCreate: A client certificate to bind to an API Key
  - `certificate` string, 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.
  - `intermediates` string[]: 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.
  - `description` string

## Response `201`

The added certificate

- ApiKeyCertificate: A client certificate bound to an API Key
  - `certificateKey` string, required: Uniquely identifies a certificate bound to an API Key
  - `fingerprint` string, 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 '+/' '-_'`.
  - `notBefore` string, date-time, required: The start of the certificate's validity period, taken from the certificate
  - `notAfter` string, date-time, required: The end of the certificate's validity period, taken from the certificate
  - `description` string
  - `created` string, date-time, required: The date and time this object was created
  - `trustAnchorFingerprint` string, 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.

## Other responses

- `400`: The request was malformed. See the response body for details
- `401`: Authentication information is missing or invalid
- `403`: The authenticated client is forbidden to make the request for the resource identified.
- `404`: The requested resource was not found
- `409`: The request could not be completed due to a conflict with the current state of the resources involved in the request.
- `422`: The request is well formed, but the current state of the resources does not allow it. See the response body for details.
- `429`: The number of requests (per minute) has exceeded the configured maximum

---

[API](https://skmtc.dev/silverflow/apis/silverflow-api.md) - [All operations](https://skmtc.dev/silverflow/apis/silverflow-api/llms.txt) - [OpenAPI document](https://skmtc.dev/silverflow/apis/silverflow-api/revisions/43ecbe4fd6ea?raw)