Skip to content
IntelliAuth

Rotate client secrets

Client secrets belong to applications that are server-side or M2M (Native and SPA don't have secrets). Rotate them when:

  • A secret is suspected of being leaked (logs, screenshots, accidental commit).
  • An employee with access to the secret leaves the company.
  • On a routine schedule (every 6-12 months is common).

The platform's rotation supports a brief overlap window so production stays up during the swap.

Where the button is

Section titled “Where the button is”

Application detail → menu (top right) → Rotate secret. Confirms in a modal.

You can also bulk-rotate via the API or the bulk-operations surface; see Bulk operations.

What happens when you rotate

Section titled “What happens when you rotate”
  1. The platform generates a new client secret.
  2. The new secret is returned ONCE in a modal. You copy it.
  3. The previous secret stays valid until previous_expires_at (default 72 hours from rotation).
  4. After 72 hours, the previous secret is invalidated.
  5. Audit log records the rotation event with actor + timestamp.

During the overlap window, both secrets work. This is the window your developers have to:

  1. Copy the new secret into the secret manager (AWS Secrets Manager, GCP Secret Manager, Vault, Kubernetes Secrets).
  2. Roll out the new value across deployments.
  3. Confirm services are using the new secret.
  4. Wait for the old to expire.

The overlap window

Section titled “The overlap window”

Default 72 hours. Configurable per-tenant.

Shorter (12-24 hours) is appropriate for:

  • Incident response, where you want the old secret out of circulation fast.
  • Tenants with mature CI/CD that can roll out a secret update in minutes.

Longer (up to 7 days) is appropriate for:

  • Tenants with slower deployment cycles or manual rollout.
  • Multi-region deployments where rolling updates take time.

Configure in Settings → Application policy → Secret rotation overlap.

Where to put the new secret

Section titled “Where to put the new secret”

The secret should land in:

  • A secret manager (AWS Secrets Manager / Vault / GCP Secret Manager / Kubernetes Secrets).
  • An env var your application reads at startup.

Never:

  • Source control (even private repos).
  • Slack / email / chat (use a password manager or a secret-sharing tool).
  • A screenshot pasted into a ticket.

The platform shows the secret in a modal you can copy from. Once you click "I've copied it", it's gone — there's no "show me again" affordance. If you missed it, you have to rotate again.

Production rollout pattern

Section titled “Production rollout pattern”

A safe rotation across a multi-instance backend:

  1. Rotate in the IntelliAuth admin console. Copy the new secret.
  2. Push the new secret to your secret manager under the same name. The previous value is shadowed but retrievable in the secret manager's version history.
  3. Trigger a rolling restart of the application. Each instance picks up the new secret as it boots.
  4. After the rolling restart completes, every instance has the new secret.
  5. Monitor for invalid_client errors — they signal an instance that still has the old secret.
  6. Wait the 72-hour overlap to absorb any stragglers (cached environments, dev machines).

A truly clean rotation has zero invalid_client errors throughout. If you see any, the rollout missed something.

When rotation fails

Section titled “When rotation fails”

The most common failure mode: a forgotten consumer of the secret. CI/CD pipelines, scheduled jobs, internal admin tools — anything that holds the secret and isn't part of the main app deploy.

To find them: in the audit log, filter on oauth.token_request_failed with error: invalid_client after the rotation. Each hit shows the IP + user agent of the caller — usually enough to identify the system.

Rotate without an overlap

Section titled “Rotate without an overlap”

In an active-incident scenario, you might want to invalidate the old secret immediately:

Application detail → menu → Revoke previous secret (visible only after a rotation has happened, while the previous is still valid).

This kills the old secret without waiting the 72 hours. Any consumer still using it gets invalid_client on the next call. Only use this when you know the old secret is hostile (in an attacker's hands) and the disruption to your own legitimate consumers is worth the immediate lockout.

SPA / Native applications

Section titled “SPA / Native applications”

SPA and Native apps don't have client secrets, so this whole topic doesn't apply. They use PKCE (a per-flow ephemeral secret) for the same security purpose, and the "rotation" of PKCE is automatic on every sign-in.