API Key Security: Revocation, Rotation, Scraping Defense

API key security is the silent reliability dimension of every API product. A leaked key drains quota, distorts billing, and contaminates analytics. A slow revocation path turns a five-minute incident into a five-hour one. A docs portal that pre-fills a real key into a "Try it" panel is a continuous credential leak anyone with browser DevTools can harvest. Most providers treat the key system as a sign-up checkbox, then discover at 2 a.m. that revocation does not actually stop traffic, rotation requires downtime, and the playground gave away a working credential for six months. This guide is the vendor-neutral checklist for evaluating the key-security posture of any API provider. Score each criterion, demand evidence, decide.

How do I evaluate the strength of an API key revocation system?

Revocation strength is the time between "I clicked revoke" and "the leaked key returns 401 from every region." Three identities have to converge for revocation to be real: the cryptographic identity stored in the database, the cached identity sitting in the API gateway memory, and the rate-limit counter identity keyed off the credential. Until all three update, the leaked key still works.

A robust revocation flow does four things in order: marks the key revoked in durable storage, invalidates cached lookup entries at the edge and in the gateway process, fans out an invalidation message to every replica, and emits a revocation event so audit logs and downstream services can react. Anything less leaves a tail of seconds to minutes where the key still works on at least one node.

Ready to ship a production-ready API integration? See Astrology API and pricing for instant activation.

Why is API key rotation harder than revocation?

API key rotation is harder than revocation because it requires both keys to coexist for long enough for every caller to switch over. A rotation that takes effect instantly is just a revocation in disguise: it breaks every active integration the moment the new key is issued. Production-grade rotation publishes the new key, accepts both keys for an overlap period that matches the slowest caller, then deprecates the old key.

Three rotation patterns work in practice. Soft rotation keeps the old key valid for 7 to 30 days. Versioned rotation ties each key to a version label so the server can apply per-version policy. Emergency rotation collapses the grace window to zero and accepts brief 401s. Pick the pattern that matches the leak severity.

How do public docs and playgrounds leak API keys?

Public documentation portals leak API keys when they ship a real working key as the default value of a "Try it" panel. Anyone with browser DevTools can open the network tab and copy the X-API-Key header out of the request. The same key surfaces in static HTML if the portal hydrates the playground server-side, in any analytics that capture request headers, and in browser history when the key is passed as a query parameter.

The mitigation is to never ship a real provisioned key into client-side HTML. Three patterns are safe: issue short-lived demo tokens scoped to a tiny quota, gate the playground behind a sign-in that mints a session token at view time, or restrict the demo key to a narrow endpoint set with aggressive caps. Combine any of these with a managed bot challenge on the docs routes so credential scrapers cannot harvest at scale.

What rate limiting and quota caps belong in a defense-in-depth model?

Rate limiting is the second line of defense after authentication. A leaked key with no quota cap is unlimited damage; a leaked key with a per-minute quota and a per-day ceiling is bounded damage. Three counters belong in a serious posture: a per-second rate limit that bounds burst abuse, a per-minute or per-hour quota that bounds sustained abuse, and a per-billing-period ceiling that bounds the total financial exposure of any single credential.

Quota caps should be visible in a usage dashboard and exposed in response headers so well-behaved clients can self-throttle. Return a JSON error payload with a machine-readable code, a retry-after hint, and headers for limit, remaining, and reset. The error contract is documented once and never changes shape.

How do publishable keys and origin allow-lists protect browser code?

Publishable keys are a key class safe to ship in client-side code because the server enforces an origin allow-list and a restricted scope. The pattern mirrors how payment providers split keys: a secret key (server-only, full scope) and a publishable key (browser-safe, scoped to a small read or compute subset, gated by Origin and Referer). A leaked publishable key is annoying, but it cannot drain the account because it cannot call billing or admin endpoints and cannot be replayed from an attacker domain.

Three checks make publishable keys effective. The server validates Origin against an allow-list registered on the customer record, rejecting other origins with a 403. The allow-list editor lives in the dashboard and supports wildcards for staging. The publishable key carries a visible prefix so reviewers spot a misclassified secret at a glance.

How does observability turn a key leak into a recoverable incident?

Observability turns key leaks from silent disasters into recoverable incidents. The minimum signal set is per-call: the credential identity, the source IP, the user agent string, the response code, and the latency. Aggregate-only logging hides the shape of an attack. Per-call logging exposes it: a single key hitting from 400 IPs across 12 ASNs in 30 minutes is unmistakable scraping; a single key hitting from one residential IP at 4 calls per minute is normal traffic from a small app.

Forensic logging is also a cardholder-dispute defense surface. When a chargeback claims unauthorized transactions, a per-call audit trail showing the same key used continuously over 30 days from the same regions, against the documented integration domains for that customer, is decisive evidence. Pair the per-call log with a public methodology page that explains what is captured and why, see methodology, so customers understand the trade-off between privacy and forensic defensibility.

What is the right API key incident response plan?

A right-sized incident response plan for a suspected key leak runs in five steps, in order. The plan is the same whether the leak source is a public GitHub repository, a leaked CI log, a compromised laptop, or an unknown vector.

1. Rotate first, investigate second. Issue a new key and switch production traffic. Revocation of the old key follows after the new key is verified live; the order matters because revocation triggers customer 401s and rotation does not.
2. Cap the quota of the suspected key to near-zero during the rotation window so the leak surface stops bleeding while you confirm the rotation worked end to end.
3. Pull the per-call audit log for the suspected key over the prior 30 days. Cluster by IP, ASN, and user agent. Anything that does not match the documented integration is in scope for the postmortem.
4. Revoke the old key once the new key is confirmed live in every region the integration calls from. Emit a revocation event into the audit log so the timeline is reconstructable later.
5. Write the postmortem against your own template, share the relevant findings with the customer, and update the prevention checklist so the same leak vector does not recur. See the API reference for how rotation, revocation, and audit endpoints fit together.

# Generic shape; your provider should expose endpoints like these.
# Step 1: issue a new key for the customer.
curl -X POST https://api.example.com/v1/keys \
  -H "Authorization: Bearer ${ADMIN_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"label":"rotation-2026-05","scope":"read"}'

# Step 2: cap the suspected key while verification runs.
curl -X PATCH https://api.example.com/v1/keys/${OLD_KEY_ID} \
  -H "Authorization: Bearer ${ADMIN_TOKEN}" \
  -d '{"rateLimitPerMinute":1}'

# Step 3: revoke the suspected key after cutover.
curl -X DELETE https://api.example.com/v1/keys/${OLD_KEY_ID} \
  -H "Authorization: Bearer ${ADMIN_TOKEN}"

// Generic shape; your provider should expose endpoints like these.
const headers = { Authorization: `Bearer ${ADMIN_TOKEN}`, 'Content-Type': 'application/json' };

const issued = await fetch('https://api.example.com/v1/keys', {
  method: 'POST',
  headers,
  body: JSON.stringify({ label: 'rotation-2026-05', scope: 'read' }),
}).then((r) => r.json());

await fetch(`https://api.example.com/v1/keys/${OLD_KEY_ID}`, {
  method: 'PATCH',
  headers,
  body: JSON.stringify({ rateLimitPerMinute: 1 }),
});

await fetch(`https://api.example.com/v1/keys/${OLD_KEY_ID}`, {
  method: 'DELETE',
  headers,
});

# Generic shape; your provider should expose endpoints like these.
import os, requests

headers = {"Authorization": f"Bearer {os.environ['ADMIN_TOKEN']}"}

issued = requests.post(
    "https://api.example.com/v1/keys",
    headers=headers,
    json={"label": "rotation-2026-05", "scope": "read"},
).json()

requests.patch(
    f"https://api.example.com/v1/keys/{os.environ['OLD_KEY_ID']}",
    headers=headers,
    json={"rateLimitPerMinute": 1},
)

requests.delete(
    f"https://api.example.com/v1/keys/{os.environ['OLD_KEY_ID']}",
    headers=headers,
)

FAQ

How do I revoke an API key without breaking active sessions?

Revoke the key only after rotating production traffic onto a new key and confirming live calls succeed. Order matters: rotation first, verification second, revocation third. Issuing a revocation before the new key is wired in causes the same 401 outage you are trying to avoid.

What is a reasonable API key rotation policy for production?

A reasonable baseline is rotation every 90 days for keys with broad scope, every 180 days for read-only or narrowly scoped keys, and immediately on any suspected exposure. Pair the schedule with an automated reminder, an overlap window of at least 7 days, and a per-call audit log so the rotation can be verified rather than assumed.

Can I detect API key scraping from a documentation portal in real time?

Yes. Per-call logging that captures source IP, user agent, and response code surfaces the signature of scraping within minutes: many distinct IPs hitting the same demo key in a short window, often from hosting ASNs rather than residential ranges. Combine the log with a managed bot challenge on documentation routes to block harvesters before the key is harvested.

Does rate limiting prevent credential abuse if a key leaks?

Rate limiting bounds the damage but does not prevent abuse. A leaked key with a per-minute cap of 60 calls and a daily ceiling of 50000 is bounded to that envelope, which makes the leak survivable. Without caps, a leaked key can drain quota, distort analytics, and run up overage charges in hours. Treat rate limiting as a containment control, not a substitute for revocation.

Should I expose API keys directly in browser code?

Never expose a full-scope secret key in browser code. Use a publishable key class that is gated by an origin allow-list and scoped to a safe read or compute subset of endpoints. Anything that mutates billing, accounts, or admin state must be called only from server code with the secret key. Publishable keys make browser integrations practical without bleeding admin reach.

When should I treat a leaked API key as a billing incident, not just a security incident?

Treat any leak that ran for more than a few hours as a billing incident in parallel with the security response. Pull the per-call audit log, separate traffic that matches the documented integration from traffic that does not, and credit the non-attributable usage. Customers extend more trust when they see operational discipline around billing recovery, not just the technical fix.

Why does my API provider hash my API key instead of storing it?

Storing only a hash of the key, with a separate stored prefix for lookup, means a database leak does not become a credential leak. The provider validates an incoming key by hashing it on arrival and comparing the digest, but cannot reconstruct the key. A provider that can email you the original key has stored it in plaintext or with reversible encryption, a weaker posture than the hashed-with-prefix pattern.

Conclusion

API key security is the convergence of revocation discipline, rotation hygiene, scraping defense, rate limiting, browser-safe key classes, per-call observability, and a runnable incident response plan. Score every provider against the eight rows in the criteria table, and score your own system the same way. See Astrology API for the shipped surface and pricing for activation.