Rotating Client Application Secret without Downtime

Problem Statement

How to eliminate downtime for the impacted system when rotating client secrets?


Instead of using the administration dashboard or the Management API endpoint (Auth0 Management API v2 ) to rotate the client secret, The following approach explains the details.


  • The system relies on the configuration to maintain either a list of client secrets or at least two separate configuration entries (CURRENT and NEXT) representing client secrets.

  • By default, the system uses the first client secret in the list or the CURRENT configuration entry. If an error is received during an exchange that requires client authentication and the error is known to be associated with a problem related to client credentials, the system should be capable of retrying the operation using the next secret in the list or the NEXT configuration entry.

  • If an event occurs that forces the system to attempt to use the next secret in the list or the NEXT configuration entry and the operation succeeds when using the new secret, the system should discard the old secret and update the configuration in a way that the next secret (the one that succeeded) is considered to be the default/current one going forward.

Process (to rotate the secret):

  1. The system associated with the client application record generates a new value for the client secret. This value should have similar entropy to the client secret values generated by the Auth0 service.
  2. The system adds the newly generated secret to the system configuration as the next secret in the list or in the respective entry if separate configuration entries are used.
  3. The system obtains a Management API access token and uses it to perform a client application update request (Auth0 Management API v2 ) by updating the client_secret with the the value generated in the first step.

Given the system is prepared to automatically fallback to use the next client secret as available in system configuration, this process will allow rotating a secret without downtime because by the time that the new secret takes effect in the Auth0 service, the system is already aware of that value and can automatically fallback and retry any operation that fails due to the old secret that got rotated.

The process above relies on the system to provide an option for administrative users to rotate the secret through the system. An alternative would be a tenant Admin manually perform the three steps in question. In other words, a tenant Admin would manually generate a new client secret value, update the system configuration with that value, and perform the client update outside the system.

For concerns regarding how to generate a client secret with sufficient entropy for rotation, it is technically possible to use a temporary client application record in Auth0. In other words, the process could create a new client application record in Auth0, retrieve the secret from the new application, delete that application, and use that secret in the context of the application that requires a rotation.