Rotating credentials — your API key's one-time secret, and the operator's provider-token drill
Who this guide is for: two audiences, clearly split:
- Part 1 — customer ADMINISTRATORS who manage their business's API keys (needs the key-management permission).
- Part 2 — platform OPERATORS (the ConvoTide side's own staff) who rotate a business's stored WhatsApp/Meta provider token.
One principle covers both: a rotated credential replaces its predecessor in one atomic step, the old one dies immediately, and the new secret is shown exactly once.
All credentials in the runs behind this guide are synthetic. Token values like
fake-meta-token-A-…and everyctk_…secret were generated by the tests and never came from a real account. No live Meta call, no live send, and no production credential was touched.
Part 1 — Rotating your business's API key (administrator)
What happens when you rotate
When you rotate a key, the answer contains:
- the old key id and a new key id — the replacement is a new key record, not an edit of the old one;
- the new one-time secret, shaped
ctk_…— this is the only moment it is ever shown. Its first 12 characters are returned as the prefix so you can recognise the key later without knowing the secret; - the replacement's permissions (scopes).
What the run verified, in storage and in use:
- The old secret is dead the moment the rotation commits. There is no grace window and no overlap — old and new are never both valid. The new secret works immediately.
- The replacement inherits the original key's identity — same business, same owner, same name, same permissions. The old record is kept with status "revoked"; the new one is "active".
- The secret is stored only as a cryptographic hash. It appears nowhere in the key list and not in the audit trail.
- The audit trail records the rotation once — who did it, the old key id, the new key id.
- Rotating one key does not touch your other keys. A second key of the same seat stayed active and kept working.
Asking for wider permissions: two ceilings bind
You may request different scopes during rotation. Two ceilings clamp the result: the replacement can never exceed the original key's scopes, nor your seat's current scopes. A replacement never gets more than both allow.
Refusals — honest, and never leaking a secret
| Situation | Answer | State after |
|---|---|---|
| Key id does not exist, is already revoked, belongs to another business or another seat | 404 NOT_FOUND | unchanged |
| Your seat is deactivated | 403 APIKEY_SEAT_DEACTIVATED | unchanged |
| Your seat lacks the key-management permission | 403 SCOPE_DENIED | unchanged |
| Malformed key id or body, missing sign-in | honest 4xx validation errors | unchanged |
No refusal ever contains a secret — old or new.
When two rotations race, or a failure strikes mid-way
- Two simultaneous rotations of the same key: exactly one wins. The loser is refused; there is never a half-rotated state.
- A mid-way failure rolls back completely — old key still active, nothing revoked, no audit row — and a retry then succeeds honestly.
The same rotation through the real screen
The same route was later driven through the real API-keys screen in a real browser (journey PASSED), re-proving every behavior above on screen:
- The screen's entry is itself factor-gated. Opening the API-keys view as the admin seat raises the privileged authenticator prompt before the key list is read.
- Cancel is inert. Clicking Rotate and answering the confirmation No sends zero rotate requests.
- Confirming sends exactly one rotate (exactly one POST, answered success).
- The
ctk_secret appears once, in the dialog. - Dismiss, refresh — never shown again. The one-time property is enforced by the product, not just promised.
- Two rows with the same inherited name appear after rotation — the revoked original and its active replacement.

The screenshot is a byte-exact capture of the passing journey (SHA256 and provenance in assets/ASSETS-MANIFEST.json). The key, the secret and the business are synthetic test fixtures; no real credential is depicted.
Part 2 — Operator drill: rotating a business's provider token (operator)
The provider token (the WhatsApp/Meta access credential a business stored during onboarding) can be rotated without touching the messaging engine's storage discipline. The proven property, end-to-end on the real dispatch engine with a fake provider:
- Provision stores the first token encrypted through the vault's public API — plaintext never reaches storage, logs, or any response.
- Send #1 presents token A.
- Rotate — one write over the stored credentials; the same operator path, no schema change.
- Send #2 presents token B with zero interruption — no restart, no failed send — when the composition reads the vault at send time.
- The old plaintext is unrecoverable from storage, and a rotation racing reads never yields a half-written credential.
The honest gap the same suite records
Today's worker composition builds its sender once per process and reads
the token from the environment at boot. The suite proves the
consequence rather than hiding it: a composition of that shape keeps
presenting token A after the stored credential was rotated — a rotation
cannot reach a running worker of that shape without a restart. Zero
interruption therefore requires either the send-time vault read (the
candidate bin.ts upgrade the suite exercises) or the operator sequence
rotate the stored credential, then restart the worker, exactly as the
operator runbook
states. The suite documents reality both ways; that is the drill working.
Evidence record (kept for honesty). Both suites ran in the FULL3747-PG lane against real ordinary-role throwaway PostgreSQL 16 clusters, on the combined candidate:
- Suite 3 —
zc3703-apikey-rotation.test.ts: 6/6 passed (2026-10-24T23:20:54Z → 23:21:14Z, exit 0), verbatim receipttools/zcode-integration3723/runtime/FULL3747-PG/logs/03-rotation.tap. The route is the real mounted router (app.use("/v1", createApiKeyRotationRouter(...))in the candidate'sapp.ts), driven over real loopback HTTP through the app-shaped seat adapter including theapikeys:managegate. - Suite 4 —
pi64-rotation.test.ts: 4/4 passed (2026-10-24T23:21:21Z → 23:21:37Z, exit 0), receiptlogs/04-pi64.tap. The provider-token property against the real worker dispatch engine with a fake provider that never performs network I/O. - Both green again on a second independent fresh-PG cycle
(
c2-03-rotation.tap6/6,c2-04-pi64.tap4/4; lane ledger "CYCLES 1+2 COMPLETE AND GREEN", 2026-10-24T23:44:30Z). - Receipts in the PG lane worktree
C:/CT-ZC-FULL3747(git-ignored); lane ledgerC:/CT-ZCODE-FULL3747/lane-pg-ledger.json. - Browser journey 2 —
real rotation keeps cancel inert and reveals one replacement once: PASSED (FULL3747-BROWSER lane, final suite result2026-10-25T00:10:00Z, ledgerC:/CT-ZCODE-FULL3747/lane-browser-ledger.json; the same SHA-bound spec/config pair as above).
Standing: combined-candidate, local evidence. Chief acceptance and publication are OPEN. No live or Main-built deployment is claimed.