Scope API credentials

An API key is a bearer credential unless the protocol adds stronger proof. Anyone who obtains it may use its authority. The server cannot tell your nightly job from an attacker holding the same string.

The common credential types differ mostly in lifetime and where authority lives. A static API key is easy to issue and lives until you revoke it. An OAuth access token is short-lived and scoped by the authorization server that issued it. A JWT carries its claims — audience, scopes, expiry — inside the token, verifiable without a lookup. Whatever you use, the scoping discipline below is the same.

One credential per job

Create separate credentials per environment and integration. A shared production key used by billing and analytics makes revocation an outage for both. Separate credentials add inventory work, but they make ownership and blast radius visible.

key_billing_prod_a91x    owner: billing-team  scope: invoices:read charges:create
key_analytics_prod_covk  owner: data-team     scope: invoices:read
key_billing_stg_m2p      owner: billing-team  scope: invoices:read charges:create

Scope permissions to what the integration actually does. Avoid URLs and browser code — a key in a query string ends up in access logs, proxies, and browser history. Store only where needed.

Log the identifier, never the secret

Log an identifier rather than the secret. Usage evidence should identify the credential without recording its value:

2026-08-03T09:12:44Z key=key_analytics_prod_covk route="GET /invoices" status=200

A last-used timestamp and expected source help responders distinguish an abandoned key from one still serving production.

Make revocation routine

Make rotation and revocation routine, not an emergency procedure you run for the first time during an incident:

# after revoking the analytics key
curl -i https://api.example.com/invoices \
  -H "Authorization: Bearer $ANALYTICS_KEY"
# HTTP/1.1 401 Unauthorized

curl -i https://api.example.com/invoices \
  -H "Authorization: Bearer $BILLING_KEY"
# HTTP/1.1 200 OK   <- billing unaffected, blast radius contained

The second request is the real test. Revoking a credential is easy; proving the revocation touched nothing else is what scoping buys you.

Replace one shared key with two scoped credentials and record their owners and permissions. Revoke the analytics key, then prove billing still works and analytics receives a denied response.