This article explains the process and implications of rotating a tenant's application signing key. Regularly rotating keys is a security best practice to protect against compromised private keys. Auth0 provides a seamless process for key rotation to ensure there is no downtime for applications that validate tokens.

• Tenant Settings
• Signing Keys
• JSON Web Key Set (JWKS)
• Management API

Auth0 uses a signing key (a public/private key pair) to sign tokens and assertions, such as ID tokens, access tokens, and SAML assertions. Applications validate these tokens using the public key. To allow for key rotation without downtime, Auth0's JSON Web Key Set (JWKS) endpoint always contains multiple keys.

Key States

At any given time, the signing keys are in one of the following states:

• Currently Used: The key that is actively being used to sign all new tokens.

• Next in Queue: The key that will become the "Currently Used" key the next time a rotation occurs.

• Previously Used: A key that was formerly the "Currently Used" key. Tokens signed with this key are still valid until the key is revoked.

A conforming client application should be able to validate tokens using any of the public keys available in the tenant's JWKS endpoint.

Performing a Key Rotation

Tenant signing keys can be rotated through the Auth0 Dashboard or the Management API.

Using the Auth0 Dashboard

1. Navigate to Dashboard > Settings > Signing Keys.

2. Under Rotation Settings, locate the Rotate Signing Key section.

3. Select Rotate Key. This action moves the "Currently Used" key to the "Previously Used" state and promotes the "Next in Queue" key to become the "Currently Used" key. A new "Next in Queue" key is also generated.
    

Using the Management API

To rotate the signing key programmatically, make a POST call to the Rotate the Application Signing Key endpoint.

Revoking a Key

After a key has been rotated and moved to the "Previously Used" state, it can be revoked. Revoking a key removes it permanently from the JWKS endpoint.

Important: Before revoking a key, ensure that all applications have had sufficient time to cache the new public key and that any tokens signed with the old key have expired. Revoking a key before a token expires will cause validation to fail for that token.

The Rotate & Revoke Key option in the dashboard performs both actions simultaneously. This will immediately invalidate tokens signed with the previous key and should be used with caution.