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:

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 every ctk_… 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:

What the run verified, in storage and in use:

  1. 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.
  2. 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".
  3. The secret is stored only as a cryptographic hash. It appears nowhere in the key list and not in the audit trail.
  4. The audit trail records the rotation once — who did it, the old key id, the new key id.
  5. 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

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:

  1. 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.
  2. Cancel is inert. Clicking Rotate and answering the confirmation No sends zero rotate requests.
  3. Confirming sends exactly one rotate (exactly one POST, answered success).
  4. The ctk_ secret appears once, in the dialog.
  5. Dismiss, refresh — never shown again. The one-time property is enforced by the product, not just promised.
  6. Two rows with the same inherited name appear after rotation — the revoked original and its active replacement.

After dismissing the one-time secret and refreshing: two rows both named Integration original key — the revoked original and its active replacement — and the secret dialog never returns

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:

  1. Provision stores the first token encrypted through the vault's public API — plaintext never reaches storage, logs, or any response.
  2. Send #1 presents token A.
  3. Rotate — one write over the stored credentials; the same operator path, no schema change.
  4. Send #2 presents token B with zero interruption — no restart, no failed send — when the composition reads the vault at send time.
  5. 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:

Standing: combined-candidate, local evidence. Chief acceptance and publication are OPEN. No live or Main-built deployment is claimed.