Rotate Credentials

Auth0 recommends you rotate key material regularly to meet your compliance needs and ensure security is not compromised by leaked private keys. You can use the Auth0 Dashboard or Management API to rotate new keys into use. You need to create a new credential, associate it with the private_key_jwt authentication method, and remove old or unused credentials.

The current application storage limit is two credentials at one time. To repeatedly rotate new credentials, you need to delete unused credentials.

To rotate your application credentials with Auth0 Dashboard:

Navigate to Auth0 Dashboard > Applications > Application and select the application you want to update.
Switch to the Credentials tab.
In the Available Credentials section, select Add New Key.
Set a name for your new credential, the public key in PEM format, and the algorithm for the new credential.
Select Add Credential.
To activate your new credential, navigate to the menu for the credential and choose Enable for Private Key JWT use.
Once you have updated your applications to use the new credential, deactivate your original credential:
1. Select Disable for Private Key JWT Use.
2. Once disabled, return to the credential menu and select Delete Credential.

In the rotation examples below, credential1 is an existing credential in use, and credential2 is a new credential to replace the existing one.

Generate a new key pair.
Create the credential resource with a POST request to the Management API.
The current application storage limit is two credentials at one time. To repeatedly rotate new credentials, you need to delete unused credentials.

Make a PATCH request to the Management API Update a Client endpoint to associate the credential to the authentication method private_key_jwt:

curl --location --request PATCH 'https://{domain}/api/v2/clients/{clientId} \
  --header 'Authorization: Bearer {managementApiAccessToken} \
  --header 'Content-Type: application/json' \
  --data-raw '{
          "client_authentication_methods": {
             "private_key_jwt": {
                "credentials": [{ "id": {credentialId1} }, { "id": {credentialId2} }]
             }
          }
   }'

Was this helpful?

Parameter	Description
`clientId`	Application you want to update.
`credentialId1`	ID for the existing credential in use.
`credentialId2`	ID for the new credential.
`managementApiAccessToken`	Access token for the Management API with the scopes `update:clients` and `update:credentials`.

Update your application to use the new private key to sign assertions for the Auth0 Authentication API.
Remove the unused key from your application.
```
curl --location --request PATCH 'https://{domain}/api/v2/clients/{clientId} \
  --header 'Authorization: Bearer $management_access_token' \
  --header 'Content-Type: application/json' \
  --data-raw '{
          "client_authentication_methods": {
             "private_key_jwt": {
                "credentials": [{ "id": {credentialId2} }]
             }
          }
   }'
```
Was this helpful?
/

Remove the unused key from your application. This will permanently delete the credential from storage. You must unassociate the credential from your application or you will not be able to remove it.

curl --location --request DELETE 'https://{domain}/api/v2/clients/{clientId}/credentials/{credentialId}' \
  --header 'Authorization: Bearer {managementApiAccessToken}

Was this helpful?

Parameter	Description
`clientId`	Application you want to update.
`credentialId`	ID for the old credential you want to delete.
`managementApiAccessToken`	Access token for the Management API with the scope `delete:credentials`.

Active credentials

To assure zero downtime, you can leave multiple credentials active during rotation. Applications can function normally using older keys until keys are updated. Applications can send signed assertions with any set of active credentials.

Auth0 recommends you minimize the time that multiple credentials are in use. The example below uses multiple associated credentials:

curl --location --request PATCH 'https://$tenant/api/v2/clients/$client_id' \
  --header 'Authorization: Bearer $management_access_token' \
  --header 'Content-Type: application/json' \
  --data-raw '{
          "client_authentication_methods": {
             "private_key_jwt": {
                "credentials": [{ "id": $credential1.id }, { "id": $credential2.id }]
             }
          }
 }'

Was this helpful?

Get Started

Rotate Credentials

Active credentials

Learn more