Rotate a platform-level secret for a customer who cannot self-serve

Use this procedure when a customer reports a stuck secret — typically a webhook signing key they suspect is leaked, a vault token still pinned to a departed employee, or a gateway-to-cloud mTLS certificate near expiry — and they cannot rotate it themselves because nobody in the org currently holds Admin or Owner. The self-service path is Rotate API keys; this page is the platform-assisted fallback.

Caution

Rotation invalidates the old secret immediately. Any integration still configured with the previous value fails on the next call. Confirm with the Owner which integrations will break and who will reconfigure them before you run step 4.

Procedure

1. Verify identity. The request must come from an authenticated Owner via support ticket. If the ticket comes from an Admin, tell them to use Rotate API keys themselves — you do not bypass the self-service path when it is available.

2. Confirm allow_platform_impersonation = true on the target org. If false, ask the Owner to re-enable (US-PLAT-12).

3. Mint a scoped impersonation token (US-PLAT-8). Set reason = "rotate stuck <secret_type> per ticket <id>" and ticket_ref to the support ticket number.

4. Call the rotation endpoint for the specific secret type:

   • Webhook signing key: POST /api/v1/webhooks/{id}/rotate-secret under the impersonation JWT.
   • Vault token: POST /api/v1/org/secrets/{id}/rotate.
   • mTLS certificate: POST /api/v1/gateways/{id}/rotate-cert — gateway will re-enrol on next heartbeat.

   Each endpoint writes <secret>.rotated to the org audit log with actor_type = 'platform_admin_impersonating' (US-PLAT-11).

5. Deliver the new secret out-of-band. Never paste the new value into the support ticket. Use the Owner’s on-file PGP key or the internal 1Password shared vault, whichever the runbook says for this customer.

6. End impersonation immediately after the handoff (US-PLAT-10). Do not leave the token open while waiting for the customer to reconfigure their side.

7. Verify in the dual audit trail. Platform audit log: platform.impersonation_started, platform.impersonation_ended. Org audit log: the rotation row plus the impersonation bookends, all correlated by impersonation_id.

Common variations

• Owner is unreachable: you cannot proceed. Platform admin is never authorised to rotate a secret at the request of an Admin or Operator. Escalate to Novalien Legal if the org is compromised and the Owner is unreachable — there is no in-product bypass (US-PLAT-13).
• Certificate is already expired: gateway is offline. Rotate first, then the customer restarts the gateway once they receive the new cert. See Gateway shows Offline for the customer-side reconnect.

Related

• Scoped impersonation — the D80 token lifecycle.
• Rotate API keys — the self-service path customers should use when they can.
• Revoke platform admin access — if you are rotating because a platform admin was compromised, not a customer secret.