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
- CLI
kynetra rotate auth-secret (status), --start, --promote - Config
KYNETRA_AUTH_SECRET
Example
# 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 secretLimits
- 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.