For security purposes, you can rotate a client secret without changing the client_id and without introducing downtime to your integration. This lets you update backend services gradually and revoke the old secret only after the rollout is complete.
This applies to OIDC clients that authenticate using a client secret, including management app clients.
Use this sequence to rotate a secret safely:
- Generate a new client secret for the client.
- Update your backend services, jobs, and integrations to start using the new secret.
- Verify that the updated systems can still obtain tokens successfully.
- Revoke the old secret after the rollout is complete.
During the transition period, both secrets remain valid so your systems can move over without changing the client_id.
Keep these rules in mind when planning the rollout:
- A client can have up to two active client secrets at the same time.
- You can't generate a third active secret until one of the current secrets is revoked.
- You can't revoke the last remaining secret.
- The
client_iddoes not change during rotation. - Existing integrations can keep working with the old secret until you revoke it.
To avoid service disruption during rotation:
- Store the new secret in your secret manager before updating application code or configuration.
- Roll out backend services gradually if multiple systems share the same client.
- Validate token retrieval after each rollout stage.
- Revoke the old secret only after all environments and scheduled processes are confirmed to use the new one.
Never expose client secrets in browser or mobile code. Store them only in secure backend systems and secret-management tools.
You can manage client secret rotation in either of these ways:
- Admin Portal > Applications > your app > your client > Client configuration: use the Client Secret 1 and 2 settings to generate and revoke secrets.
- API: Use the client secret management endpoints under
/v1/applications/{appId}/clients/{clientId}/secrets.