2026 Reporting a Compromised API Key vs Quietly Rotating — What the Record Buys
Short answer: Reporting a compromised API key is usually worth the record; quietly rotating one is safe only when logs prove no use, because rotating without attribution can erase what the record buys finance.
The least complex response is a documented, dual-key rotation: issue a new credential, move traffic, revoke the old one, and attach both identities to every billing event. Report the compromise when evidence or policy requires it. A quiet rotation is acceptable only when the old key is demonstrably unused and the exposure window is bounded.
| Response | Billing attribution | Incident evidence | Operational risk |
|---|---|---|---|
| Report, then rotate with overlap | Strong: old and new key IDs remain joinable | Strong: disclosure time and actions are recorded | A little process overhead |
| Rotate quietly with an audit event | Conditional: depends on complete key-to-event mapping | Medium: no external incident record | Lower short-term coordination |
| Revoke immediately and replace | Weak for in-flight charges | Strong for containment, weak for reconstruction | Highest outage risk |
Do not revoke first.
My default is the first row. It preserves the ledger while giving security and compliance a factual record to review. The choice turns on two tests: can finance attribute each charge to the right credential, and can responders prove what happened without guessing?
Should reporting a compromised API key replace quietly rotating it?
An API credential rarely serves as the billing identity by itself. A payment request usually carries a merchant account, environment, service name, and an idempotency key. If the credential ID is omitted from the event, a later rotation makes old and new traffic look identical. That is where a clean-looking fix becomes an accounting defect.
That gap gets expensive.
Keep an immutable event for each credential transition. At minimum it needs a key fingerprint (never the secret), principal, environment, reason code, actor, and timestamps in UTC. Use a monotonic event ID so a replayed log line cannot create a second transition. The transition record is not a customer-facing confession; it is a durable fact that lets finance and security reconcile the same timeline. This record has limits: it cannot prove who copied a secret, recover dropped telemetry, or turn an inferred request join into a cryptographic fact. Those gaps belong in the incident notes.
A report changes the evidence boundary. It records when the organization learned of possible exposure, what scope was considered, and who approved containment. If investigation later finds no misuse, that record still explains why the credential changed. Quiet handling can be correct, but only if the same fields exist internally and retention meets the applicable policy.
Two decision tests that survive an audit
First, test attribution accuracy. Sample a fixed window, such as 15 minutes before and after cutover, and join every charge to a credential fingerprint, service revision, and request id. A missing join is a stop signal, not a rounding error. Test retries too: an idempotent retry may arrive after revocation while representing an authorization made with the old credential.
Second, test evidence integrity. Logs should be append-only, access-controlled, and timestamped with a consistent clock source. OWASP's Secrets Management Cheat Sheet calls for lifecycle controls, rotation, and monitoring; those controls matter more than the button that creates the replacement key. Keep the old fingerprint available for the retention period, but never retain the secret value.
I benchmark this path as a workflow, not a single API call: issuance latency, percentage of requests carrying a fingerprint, reconciliation lag, and rollback time. Config bloat hides failures, so put the policy in one small record and make services consume it instead of copying flags into every deployment.
A small implementation that keeps the ledger joinable
The following TypeScript sketch models the cutover. It uses generic interfaces so the same contract can sit over a hosted secret store or a self-managed one. The important part is the event ordering: publish the new fingerprint, switch traffic, verify, then revoke.
type CredentialState = "active" | "draining" | "revoked";
interface Credential {
id: string;
fingerprint: string;
state: CredentialState;
}
interface RotationEvent {
eventId: string;
oldFingerprint: string;
newFingerprint: string;
actor: string;
reason: "suspected-exposure" | "scheduled";
occurredAt: string;
}
async function rotateProductionKey(
store: { issue(): Promise<Credential>; setActive(id: string): Promise<void>; revoke(id: string): Promise<void> },
current: Credential,
actor: string,
): Promise<RotationEvent> {
const next = await store.issue();
await store.setActive(next.id);
const event: RotationEvent = {
eventId: crypto.randomUUID(),
oldFingerprint: current.fingerprint,
newFingerprint: next.fingerprint,
actor,
reason: "suspected-exposure",
occurredAt: new Date().toISOString(),
};
await verifyBillingJoins(current.fingerprint, next.fingerprint);
await store.revoke(current.id);
await appendImmutable(event);
return event;
}
async function verifyBillingJoins(oldFp: string, newFp: string): Promise<void> {
// Check both fingerprints against the cutover window before revocation.
await Promise.resolve([oldFp, newFp]);
}
async function appendImmutable(event: RotationEvent): Promise<void> {
await Promise.resolve(event);
}
In production, verifyBillingJoins should fail closed if the billing stream is delayed or if either fingerprint has no sample events. The overlap period is a control, not a comfort blanket. Set its end from observed traffic and queue drain time; two minutes may work for one service and be unsafe for another.
When is immediate revocation the right runner-up?
Immediate revocation wins when there is credible active abuse, a key has broad tenant scope, or policy sets a hard containment deadline. Accept the attribution gap as a known incident cost, then recover it from gateway logs, signed request metadata, and the payment processor's idempotency records. Do not pretend those sources are equivalent to a credential fingerprint; label inferred joins as inferred.
A quiet rotation is the better runner-up when exposure is a false positive, the key is unused, and independent logs can prove that no requests arrived during the window. Still create an internal transition event. “Quiet” should mean no unnecessary blast radius, not no record. Limitation: this option does not fit an active-abuse case or a retention policy that requires formal notification; report and contain those incidents instead.
Tool choice follows the contract. A general secret manager can issue versions and enforce access policy; a cloud-native manager may integrate more tightly with deployment identity; a database-backed store can be easier to run but puts rotation locking and audit durability on your team. HashiCorp Vault, AWS Secrets Manager, Google Secret Manager, and Azure Key Vault describe different operational boundaries, not different answers to the attribution problem. Compare them on version visibility, audit export, lease behavior, and failure handling. A hosted manager is a poor fit when its audit export cannot reach the finance archive; a self-managed store is a poor fit when your team cannot operate its locking and retention.
The practical decision rule is short: report when the evidence or policy crosses its threshold, and always rotate through a joinable, two-credential state. That keeps a production service available while preserving the billing record that explains every charge.
Top comments (0)