Rotate signing keys

POST /v1/signing-keys:rotate · permission signing-keys:write

Runs a signing key rotation now, outside the automatic schedule.

• mode: immediate: the regular rotation step runs at once. The pre-published next key starts signing, the old active key stays retired for 7 days and a new next key is published. If next uses a different algorithm than the active key (an algorithm change) and was published less than 7 days ago, the call fails with 409 next_key_too_young.
• mode: emergency (suspected key compromise): the old active key is revoked and leaves the JWKS immediately; next becomes active and a new next is generated. revoke_next: true revokes next as well and activates a freshly generated, never-published key. revoke_sessions: true also revokes every session and refresh token family of the environment, so users sign in again. reason is required.

Federation keys

use can also name one of the environment's federation keys: saml_sp_signing and saml_sp_encryption (the SAML service provider signing and encryption keys published in your SP metadata) or oidc_rp_signing (the private_key_jwt key of enterprise OIDC connections, published at /sso/jwks.json). These keys are always RSA-3072 and rotate once a year on their own: a new next key is published 30 days before it takes over, and the old key stays published for 30 days after.

• mode: immediate makes that pre-published next key active now; the old key stays published for 30 more days (it appears in retired_kids). Without a published next key the call fails with 409 conflict; if the next key was published less than 7 days ago, with 409 next_key_too_young.
• mode: emergency removes the active key from the metadata or JWKS immediately and destroys its private key (revoked_kids). The published next key becomes active; if there is none, or with revoke_next: true, a new, never-published key does. Identity providers that load your metadata or JWKS from its URL pick the change up on their next refresh. Providers where you uploaded the metadata or certificate by hand reject sign-ins until you upload the new certificate; for that case a connection.sp_certificate_rotation_started webhook event is sent for each affected connection.

For a federation key, next_kid in the response is null, removed_kids is empty and revoke_sessions is not allowed. If the environment never used SAML or private_key_jwt, there is no key to rotate and the call fails with 409 conflict.

Connection keys

A SAML connection can have its own dedicated SP keys instead of the environment's. To rotate those, add connection_id (conn_…) with use: saml_sp_signing or saml_sp_encryption. The same modes, permissions and rules apply, but only that connection's key set changes: the environment's keys and the other connections' keys stay as they are, and the connection.sp_certificate_rotation_started event is sent for that connection only. The audit record names the environment as its target and the connection in metadata.connection_id. An unknown connection, or a connection of another environment, fails with 404 not_found; a connection that uses the environment's keys fails with 409 connection_keys_not_dedicated (rotate the environment's keys without connection_id). Without connection_id the environment's key set is rotated.

Emergency mode needs, besides signing-keys:write, the signing-keys:emergency permission granted explicitly on the credential: only a restricted key or an M2M client carrying that permission can call it. A full-access secret key (idp_sk_…) gets 403 insufficient_permissions in emergency mode.

New token signing keys use the algorithm of the environment policy (get the policy). A successful token signing key rotation emits the signing_key.rotated or signing_key.revoked webhook event; every rotation writes a management audit record. This endpoint belongs to the "key and secret issuance" rate limit family. Send an Idempotency-Key: a retry after a network error then returns the first result instead of rotating twice.

Request

JSON body (unknown fields are rejected with 400 unknown_field):

With mode: immediate, sending revoke_sessions: true, revoke_next: true or a reason fails with 422 (not_allowed). A connection_id with token_signing or oidc_rp_signing fails the same way.

Response

200 OK with the result of the rotation. activated_kid is the key that signs from now on and next_kid the newly published next key (null for a federation key). retired_kids are keys that stopped signing and stay published (7 days for a token signing key, 30 days for a federation key); revoked_kids are keys removed from the JWKS by an emergency rotation; removed_kids are retired keys whose 7-day window ended and that left the JWKS in the same step.

{
  "mode": "immediate",
  "use": "token_signing",
  "activated_kid": "ypeBEsobvcr6wjGzmiPcTaeG7_gUfE5yuYB3ha_uSLs",
  "next_kid": "GKw-c0PwFokMUQ6T-TUmEWnZ4_VlQ2Qpgw-vCTT0-OQ",
  "retired_kids": ["PiPoFgA5WUoziU9lZOGxNIu9egCI1CxKy3PurtWcAJ0"],
  "revoked_kids": [],
  "removed_kids": ["Ln0sA6lQeuJl7PW1NWiFpTOTogKdJBOUmXJloaJa78Y"],
  "revoke_sessions": false
}

Errors

Example

Regular rotation:

curl -X POST "https://api.eu.keenauth.com/v1/signing-keys:rotate" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"mode":"immediate"}'

Emergency rotation with a restricted key that grants signing-keys:write and signing-keys:emergency:

curl -X POST "https://api.eu.keenauth.com/v1/signing-keys:rotate" \
  -H "Authorization: Bearer $KEENAUTH_EMERGENCY_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"mode":"emergency","revoke_sessions":true,"reason":"INC-2041 key exposure"}'

Emergency rotation of the SAML SP signing key, also revoking the published next key:

curl -X POST "https://api.eu.keenauth.com/v1/signing-keys:rotate" \
  -H "Authorization: Bearer $KEENAUTH_EMERGENCY_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"mode":"emergency","use":"saml_sp_signing","revoke_next":true,"reason":"INC-2042 SP key exposure"}'

Emergency rotation of the dedicated SAML SP signing key of one connection:

curl -X POST "https://api.eu.keenauth.com/v1/signing-keys:rotate" \
  -H "Authorization: Bearer $KEENAUTH_EMERGENCY_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"mode":"emergency","use":"saml_sp_signing","connection_id":"conn_01h2xcejqtf2nbrexx3vqjhp41","reason":"INC-2043 connection key exposure"}'