Skip to main content

Rotate JSON Web Token (JWT) secrets

JSON Web Token (JWT) secrets are used to sign JWTs for a tenant. You can rotate the JWT secret for your tenant when you need to refresh the signing secret.

Prerequisites

To rotate JWT secrets, you must have:

  • A profile with the tenant-admin role.
  • chef-platform-auth-cli installed.
  • An authenticated profile configured.

What rotation affects

After rotation, both secrets are valid:

  • New secret: Used to sign new JWTs immediately.
  • Old secret: Remains valid for JWT verification for 5 days so existing tokens don’t break mid-session.

After the 5-day grace period ends, the old secret no longer validates JWTs. The next rotation after the grace period deletes the old secret from the Secrets Service.

Rotate JWT secrets

You can rotate the JWT secret for the current tenant.

To rotate the JWT secret, use the user-account jwt rotate-jwt-secret command:

chef-platform-auth-cli user-account jwt rotate-jwt-secret --profile <PROFILE_NAME>

Replace <PROFILE_NAME> with the profile associated with your tenant-admin user, for example ta.

When the command succeeds, the CLI returns the following message:

rotate-jwt-secret is successful

Thank you for your feedback!

×