> ## Documentation Index
> Fetch the complete documentation index at: https://docs-dev-docs-event-stream-action-templates.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Describes how to rotate existing credentials in the Auth0 Dashboard.

# 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 <Tooltip tip="Auth0 Dashboard: Auth0's main product to configure your services." cta="View Glossary" href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or <Tooltip tip="Auth0 Dashboard: Auth0's main product to configure your services." cta="View Glossary" href="/docs/glossary?term=Management+API">Management API</Tooltip> 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.

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  The current application storage limit is two credentials at one time. To repeatedly rotate new credentials, you need to delete unused credentials.
</Callout>

<Tabs>
  <Tab title="Use Auth0 Dashboard">
    To rotate your application credentials with Auth0 Dashboard:

    1. Navigate to [**Auth0 Dashboard > Applications > Application**](https://manage.auth0.com/#/applications) and select the application you want to update.
    2. Switch to the **Credentials** tab.
    3. In the **Available Credentials** section, select **Add New Key**.
    4. Set a name for your new credential, the public key in PEM format, and the algorithm for the new credential.
    5. Select **Add Credential**.
    6. To activate your new credential, navigate to the menu for the credential and choose **Enable for Private Key JWT use**.
    7. 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**.
  </Tab>

  <Tab title="Use Management API">
    In the rotation examples below, `credential1` is an existing credential in use, and `credential2` is a new credential to replace the existing one.

    1. Generate a new key pair.

    2. Create the credential resource with a `POST` request to the Management API.

           <Callout icon="file-lines" color="#0EA5E9" iconType="regular">
             The current application storage limit is two credentials at one time. To repeatedly rotate new credentials, you need to delete unused credentials.
           </Callout>

    3. Make a PATCH request to the Management API [Update a Client](https://auth0.com/docs/api/management/v2#!/Clients/patch_clients_by_id) endpoint to associate the credential to the authentication method `private_key_jwt`:

       ```bash lines theme={null}
       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} }]
                    }
                 }
          }'
       ```

       | 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](/docs/secure/tokens/access-tokens/management-api-access-tokens) with the scopes `update:clients` and `update:credentials`. |

    4. Update your application to use the new private key to sign assertions for the Auth0 Authentication API.

    5. Remove the unused key from your application.

       ```bash lines theme={null}
       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} }]
                    }
                 }
          }'
       ```

    6. 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.

       ```bash lines theme={null}
       curl --location --request DELETE 'https://{domain}/api/v2/clients/{clientId}/credentials/{credentialId}' \
         --header 'Authorization: Bearer {managementApiAccessToken}
       ```

       | 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](/docs/secure/tokens/access-tokens/management-api-access-tokens) with the scope ` delete:credentials`. |
  </Tab>
</Tabs>

### 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:

```bash lines theme={null}
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 }]
             }
          }
 }'
```

## Learn more

* [Configure Private Key JWT Authentication](/docs/get-started/applications/configure-private-key-jwt)
* [Application Credentials](/docs/secure/application-credentials)
* [Credential Settings](/docs/get-started/applications/credentials)