Skip to main content

Emergency Key Revoke

Immediately invalidate a leaked or compromised API key.

If you have any reason to believe an API key has been exposed (a public commit, a security alert from your monitoring, a former employee with credentials), use emergency revoke instead of standard rotation. Emergency revoke is destructive: there is no 24-hour grace window. The old key dies the moment you confirm, and any integration still using it will start failing.

When to use this vs. rotation​

  • Rotation is for routine key hygiene (~every 90 days). The old key remains valid for 24 hours so you can deploy the new one without downtime. Rotation requires a fresh two-factor step-up and is rate-limited.
  • Emergency revoke is for suspected compromise. The old key dies immediately. The cooldown is bypassed. Use this only when you have reason to believe the key is in the wrong hands.

If you are not sure which to use, prefer rotation; it is the safe default.

How it works​

Emergency revoke is a dashboard action. There is no API call for it, under any credential: a compromised key must not be able to rotate itself silently, so it is reachable only by a signed-in operator with a fresh two-factor step-up, never by any rail_* key, even on itself.

In your dashboard, go to Developers → API Keys, find the compromised key, and click the red Emergency revoke button. You are asked to type your merchant account name exactly (case-sensitive) to confirm (the same friction pattern as AWS IAM's destructive operations), and you can attach an optional incident note, up to 280 characters, recorded in your audit log only and never included in a webhook payload. The dashboard handles your session and the confirmation for you.

What happens​

A new key is issued in the same mode and the old one dies immediately: no grace window, no cooldown. The new key's plaintext is shown once, via copy-to-clipboard; there is no way to retrieve it again. Copy it immediately, update your integration, and only then close the tab.

If someone else on your team already emergency-revoked this key a moment earlier, the dashboard tells you so; it does not show you the now-active key in that moment, so reload the key list to see it. There is one revoke event, and whichever operator's click reaches it first wins; both attempts are recorded in your audit log.

Webhook event​

A successful emergency revoke triggers a key_emergency_revoked event delivered to every webhook endpoint you have registered. The payload:

{
  "key_id": "prd_<old>",
  "new_key_id": "prd_<new>",
  "key_prefix": "rail_full_live_",
  "revoked_at": "2026-05-11T15:00:00.000Z",
  "revoked_by": {
    "actor_type": "merchant",
    "actor_id": "<16-char opaque hash>"
  },
  "reason": "suspected_compromise"
}

The revoked_by.actor_id field is a stable opaque identifier, useful for correlating multiple actions from the same operator across events. The new key's plaintext is never in the webhook payload; only the new key id and prefix appear. Your reason_note (if you provided one) is also never in the webhook payload; it lives only in your audit log.

The webhook is signed with TensorRail-Signature (HMAC-SHA512) like every other event TensorRail emits. See Webhooks for the verification pattern.

Audit log​

Every emergency revoke, successful or rejected, is recorded in your merchant audit log. Visit the Audit tab in the dashboard to see the full history. Each entry captures:

  • The operator who triggered the request (the signed-in dashboard operator).
  • IP address, user agent, request ID.
  • The key revoked and the new key issued.
  • Your optional reason_note.
  • The outcome (success, confirmation mismatch, race lost to another operator).

See also​