API keys vs OAuth: a static secret is not a session

API keys and OAuth tokens both travel in HTTP headers and both grant access to an API. That is where the similarity ends.

The difference is what they answer: an API key says which application is calling; an OAuth token says what this grant allows, often on behalf of a user. Choosing the wrong one shows up later as over-permissioned integrations and leaky credentials.

Side by side

When API keys are fine

API keys are not obsolete. They fit when:

• The caller is a trusted server, not a browser.
• The access is not on behalf of a user — a map API, a weather feed, a payment gateway's server call.
• The key can be scoped to a project or environment.
• You can rotate it without breaking customers.

The classic example is a public API with usage tiers: each customer gets a key, rate limits are applied per key, and the key identifies who pays.

When API keys fall short

They become the wrong tool when:

• The key is in a browser or mobile app. Anyone can extract it; treat it as public.
• Access needs user context. A key cannot say "this is Alice".
• Permissions differ per customer or per user. One key with full access cannot express it.
• Revocation must be fast. A leaked key stays valid until someone rotates it.
• Audit needs attribution. "Which employee did this?" is unanswerable with a shared key.

OWASP's API Security Top 10 lists broken authentication — including weak or leaked credentials — as a top API risk for exactly these reasons.

Where OAuth fits

Use OAuth when:

• A third party acts on behalf of a user and needs scoped access.
• Access must expire and be revocable.
• Different clients need different permissions.
• You need auditability per grant.

For machine-to-machine calls, OAuth's client credentials grant is the closest analogue to an API key — but with short-lived tokens, scopes and central rotation. It is more work to set up and safer to operate.

The hybrid pattern

Many APIs use both:

1. The customer is issued a client ID and secret (or a private key).
2. The client exchanges them at the token endpoint for a short-lived access token.
3. The access token is scoped and expires; the client refreshes as needed.

This keeps the long-lived secret out of most requests and gives you revocation, scoping and audit for free.

If you do use API keys

The minimum discipline:

• Treat keys as secrets: hashed at rest, never in logs, never in URLs.
• One key per environment and per customer, with a recognizable prefix so scanners can detect leaks.
• Show the key once at creation; store only a hash.
• Track last used, and alert on keys used from unexpected places.
• Rotate on a schedule and after any suspected exposure, with an overlap window.
• Scope and rate-limit per key, even if the scope is just "project X".
• Support revocation that takes effect immediately.

A key-management page that shows "last used" and a Revoke button prevents more incidents than any amount of documentation.

A decision checklist

1. Is a user involved? If yes, OAuth.
2. Does the permission set differ per caller? If yes, OAuth.
3. Must access expire automatically? If yes, OAuth or short-lived tokens.
4. Is the caller a server you control, with simple access? API key is acceptable.
5. Can you rotate keys without downtime? If not, fix that before shipping keys.

Related reading: OAuth scopes, what OAuth 2.0 is and OAuth grant types.