Skip to main content

Client secret grace period

When you rotate the client secret for an OAuth application, ChainIT can optionally keep the previous secret valid for a limited time. That overlap is called the grace period (configured in seconds).

Why use a grace period?​

Rotating a secret invalidates the old value for the client credentials grant and for any back-channel API call that authenticates with client_secret_basic / client_secret_post. Without a grace period, any server that still has the old secret in memory or on disk will start failing immediately. (ID-token verification itself is unaffected — ChainIT signs ID tokens with RS256 using a key published in JWKS, not with your client secret.)

A grace period gives your team time to:

  • Roll out the new secret to every environment (staging, production, workers).
  • Finish in-flight token exchanges that still use the old secret.
  • Roll back quickly if a deployment mistake is detected.

How to configure it​

  1. Open the Developer Portal and select your application.
  2. On Overview, use Rotate Client Secret (or the equivalent rotate action for your app).
  3. In Grace Time (seconds), enter a non‑negative integer. Leave the field empty if you do not need a custom overlap window.

The portal suggests 86400 seconds (24 hours) when you need a full day to roll the new secret out everywhere.

Units

Grace time is always specified in seconds (whole numbers only).

What happens during the window​

While the grace period is active, both the newly generated secret and the previous secret may be accepted by ChainIT for operations that rely on the client secret (for example, the token endpoint or symmetric ID token checks). Exact behavior is enforced by ChainIT’s authorization service; treat the grace window as a migration aid, not a permanent dual-secret mode.

Security

A longer grace period is more convenient but extends the window in which a leaked old secret remains useful. Prefer the shortest duration that still lets you update all callers, then confirm rotation is complete.

Related topics