Identity & access

Signing-secret rotation

Lets an operator replace the platform token-signing secret without editing data by hand.

BetaEngine edition 5f8ea3af

What it does

A two-step command mints a pending secret that the server accepts alongside the active one, then promotes it. The command runs against the data directory with the kynetra tool, and the server loads each change when it restarts.

How it works

kynetra rotate auth-secret --start generates a new 64-byte secret and stores it as a pending record. After the server restarts it holds two secrets: the active one signs new tokens and either one verifies. kynetra rotate auth-secret --promote then writes the pending secret as the active one, deletes the pending record and discards the old secret. Access tokens signed under the old secret stop verifying at that point. Refresh tokens are stored hashes rather than signed values, so they survive the change and let clients obtain new access tokens. Short-lived MFA challenge tokens are signed with keys derived from the active secret and stop verifying too.

Running kynetra rotate auth-secret with neither flag prints whether a rotation is in progress, which is useful between the two steps.

Projects have their own signing secrets. They are replaced together with the project keys by the key-rotation route described under project API keys, with no overlap window.

If the signing secret is supplied through KYNETRA_AUTH_SECRET, the server refuses to start when the variable differs from the stored secret. The promoted value is generated by the command and is not shown, so remove the variable after promotion. A replica takes its primary's record. A clustered node that takes the secret from the environment and never stores it needs a different procedure, which this command does not cover.

Where you reach it

  • CLIkynetra rotate auth-secret (status), --start, --promote
  • ConfigKYNETRA_AUTH_SECRET

Example

Rotate the platform signing secretbash
# 1. Mint a pending secret (run where the data directory is available)
kynetra --data ./.kynetra rotate auth-secret --start

# 2. Restart kynetra-server so that it loads the pending secret

# 3. Promote it: access tokens signed under the old secret stop verifying
kynetra --data ./.kynetra rotate auth-secret --promote

# 4. Restart again so the server signs with the promoted secret

Limits

  • The command always works on the local data directory given by --data, even when --remote is set. It does not contact a server, and no HTTP route performs the rotation.
  • Promotion ends the old secret at once. Nothing signs with the pending secret before promotion, so access tokens issued before promotion stop verifying at that moment.
  • Restart the server after each step so that it loads the change.
  • The command writes no audit entry.
  • Rotation on a schedule is not available; see the secret rotation machine page.

Evidence

  • On this siteSecurity overview
  • Tests4 rotation tests (old secret valid during overlap, new secret valid after promotion, old secret invalid after promotion, promotion with no pending secret fails) and 26 start-up secret tests across the auth crate and the server

Test coverage is listed as present in the engine repository at this edition. This page does not report test results.

KynetraDB is in private preview

Request a preview to talk through the limits above against your own workload.