Authentication method client certificates

Use the OIDC client-key resource to manage up to two client certificates for an existing OpenID Connect authentication method. The primary certificate is used for client authentication with private key JWT. A secondary certificate lets you prepare a replacement before making it primary.

Follow the Control API authentication and access guidance. The Swagger contract defines the current operations, request fields and responses.

Import and replace certificates

Import a PKCS#12 (.p12 or .pfx) file containing the certificate and its private key. Supply its password when required. Invalid files, incorrect passwords and missing private keys are rejected before saving.

Imports target the primary position by default. Set isPrimary to false to add or replace the secondary certificate; a primary certificate must already exist. Replacing either certificate preserves the other one.

Reading or importing through the client-key resource returns public information about both certificates, including their external names. Private keys are not returned. You can use the certificate-reading helpers to inspect a file before importing it.

Rotate a client certificate

1. Import the replacement as the secondary certificate.
2. Register its public certificate with the external identity provider.
3. Select the secondary key's external name as primary using the update operation. The previous primary becomes secondary. Selecting the current primary again leaves the order unchanged.
4. Remove the old secondary certificate when it is no longer needed.

Deleting the primary certificate makes the remaining secondary certificate primary. Deleting the only certificate leaves the authentication method without a client certificate for private key JWT.