API Keys vs OAuth Tokens

By Michael Samuel Naeem · May 15, 2025 · 5 min read

The mobile app shipped with sk_live_abc123 in the APK. Scrapers found it within hours. API keys are shared secrets: whoever possesses the string is the caller. OAuth access tokens are also bearer credentials, but they are short-lived, scoped, auditable, and issuable only after user consent or a vault-stored client secret. Choosing between them is not religious—it is threat modeling for who holds the credential and what happens when it leaks.

API keys: simple and dangerous

Keys excel for:

• Internal batch jobs in your VPC
• Webhook verification paired with HMAC signatures
• Developer sandboxes with spend caps

Design rules:

GET /v1/balances HTTP/1.1
Authorization: Bearer sk_live_7kQ2...

Store HMAC-SHA256(key) in the database. Prefix keys (sk_live_, sk_test_) so grep catches accidents. Enforce one key per integration for blast-radius isolation.

Validate this in staging with production-like data volume before declaring done. Capture metrics baseline the week before change and compare for seven days after—subtle regressions hide in aggregates until a large tenant hits the path. Update the on-call runbook with the failure signature and rollback command so responders need not rediscover steps during an incident.

OAuth for user-delegated access

Authorization Code + PKCE flow for SPAs and mobile:

1. User authenticates at IdP
2. App receives code, exchanges for access + refresh tokens
3. Access token carries scopes like orders:read

Revocation endpoint invalidates refresh tokens per client. Users disable a rogue integration without rotating their password.

Validate this in staging with production-like data volume before declaring done. Capture metrics baseline the week before change and compare for seven days after—subtle regressions hide in aggregates until a large tenant hits the path. Update the on-call runbook with the failure signature and rollback command so responders need not rediscover steps during an incident.

Machine-to-machine OAuth

Client Credentials grant for service accounts:

curl -X POST https://auth.example.com/oauth/token \
  -d grant_type=client_credentials \
  -d client_id=svc_inventory \
  -d client_secret=$SECRET \
  -d scope=inventory:write

Prefer private_key_jwt or mTLS instead of static client secrets for high-assurance partners. Rotate secrets via dual-active window.

Validate this in staging with production-like data volume before declaring done. Capture metrics baseline the week before change and compare for seven days after—subtle regressions hide in aggregates until a large tenant hits the path. Update the on-call runbook with the failure signature and rollback command so responders need not rediscover steps during an incident.

Scopes beat monolithic keys

Map scopes to authorization policies:

{
  "sub": "user_42",
  "scope": "reports:read invoices:read",
  "exp": 1710000000
}

A leaked read-only token cannot POST transfers. API keys can emulate scopes only by issuing multiple keys—operationally heavier.

Validate this in staging with production-like data volume before declaring done. Capture metrics baseline the week before change and compare for seven days after—subtle regressions hide in aggregates until a large tenant hits the path. Update the on-call runbook with the failure signature and rollback command so responders need not rediscover steps during an incident.

Rotation and incident response

During incidents, disable key ID in admin console immediately; OAuth allows global session revocation at IdP.

Validate this in staging with production-like data volume before declaring done. Capture metrics baseline the week before change and compare for seven days after—subtle regressions hide in aggregates until a large tenant hits the path. Update the on-call runbook with the failure signature and rollback command so responders need not rediscover steps during an incident.

Hybrid patterns

Some products expose API keys that mint short-lived JWTs server-side—keys never leave the backend you control. Public documentation keys for try-it-now flows should be rate-limited sandbox keys with no production data.

Prefix keys sk_live_ and sk_test_ so grep catches accidents in repos. Enforce one key per integration for blast-radius isolation. Hash at rest; show plaintext once at creation.

Hybrid products expose server-side keys that mint short-lived JWTs—keys never ship in mobile binaries. Sandbox documentation keys need rate limits and synthetic data only.

During incidents disable key ID in admin console immediately. OAuth allows global session revocation at IdP. Document rotation playbooks for both models with different user impact expectations.

Validate this in staging with production-like data volume before declaring done. Capture metrics baseline the week before change and compare for seven days after—subtle regressions hide in aggregates until a large tenant hits the path. Update the on-call runbook with the failure signature and rollback command so responders need not rediscover steps during an incident.

Document the decision, owner, and rollback path in your team wiki the same week you ship. Future you will not remember which environment variable toggled the behavior unless it is written next to the runbook entry and linked from the alert. That habit costs ten minutes per change and saves hours when pagination or auth misbehaves under a single large tenant.

Run the change through your standard PR checklist: tests, observability, and a two-minute rollback drill in staging. Small operational habits accumulate into systems that survive on-call nights without heroics.

Share a short write-up in your engineering channel after rollout: what shipped, what metric you watch, and who owns follow-up. That closes the loop for teammates who were not in the PR and surfaces gaps in docs before the next person repeats the same investigation.

Resources

• OAuth 2.0 RFC 6749
• OAuth 2.1 draft security best current practice
• OWASP API Security: broken authentication
• Stripe API keys documentation
• Auth0: API vs M2M authorization