Add an IdP signing certificate to a connection
POST /v1/connections/{connection_id}/certificates · permission connections:write
Adds a signing certificate of the identity provider to an enterprise SAML connection. Use it to upload the certificate by hand or to rotate certificates: add the new certificate first, switch the identity provider over, then delete the old one. Rotation takes effect immediately, also on an active connection.
The certificate is one PEM CERTIFICATE block (at most 8 KiB). It must not be expired and must have an RSA key of at least 2048 bits or an ECDSA P-256, P-384 or P-521 key. When it is rejected the response does not say why, and neither the reason nor the certificate content is logged. A connection has at most 3 active certificates. A certificate that was deleted from the connection cannot be added again. The request takes no If-Match header. Writes are audited as connection.idp_certificate_added.
Request
| Field | Type | Required | Description |
|---|---|---|---|
connection_id |
path | yes | Enterprise SAML connection ID (conn_…). |
certificate |
string | yes | One PEM certificate (-----BEGIN CERTIFICATE----- …), at most 8 KiB. |
Response
201 Created with the new certificate (see List certificates). When the same certificate is already on the connection the response is 200 OK with the registered certificate; nothing is written or audited.
{"id": "conncert_01j9xq2m4n6p8r0s2t4v6w8y0a", "sha256_fingerprint": "3b0c…", "not_before": "2026-01-01T00:00:00Z", "not_after": "2028-01-01T00:00:00Z", "source": "manual"}
Errors
| HTTP | code | When |
|---|---|---|
| 404 | not_found |
The connection does not exist in this environment or is not an enterprise connection. |
| 409 | conflict |
The connection is not a SAML connection, has no SAML configuration yet, already has 3 active certificates, or the certificate was deleted from it before. |
| 422 | validation_failed |
The certificate is missing, too large or not accepted; errors[] points at /certificate. Staging and production environments also refuse a certificate over the public test key of the local mock server. |
| 400 | unknown_field |
The body has an unknown field. |
| 401 | unauthenticated |
The credential is missing, invalid or revoked. |
| 403 | insufficient_permissions |
The credential lacks the required permission. |
| 429 | rate_limited |
The rate limit was exceeded; retry after the Retry-After period. |
| 503 | service_unavailable |
A dependency is temporarily unavailable; retry after the Retry-After period. |
Example
jq -Rs '{certificate: .}' idp-signing.pem > cert.json
curl -X POST "https://api.eu.keenauth.com/v1/connections/conn_01j9xp6q0r1s5t7v9w1x3y5z7b/certificates" \
-H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
-H "Content-Type: application/json" \
-d @cert.json
keenauth connections certificates add conn_01j9xp6q0r1s5t7v9w1x3y5z7b --certificate-file idp-signing.pem