API design

OAuth vs API keys

API designAuthorizationDecision guide

Short answer

Use API keys for simple, server-to-server identification where one owner controls both sides. Use OAuth when a client acts for a user or needs scoped, revocable, delegated access; OAuth’s setup cost is justified by short-lived tokens, consent, and independent resource ownership.

Written and reviewed by Sahil Srivastav

What each one actually is

An API key is a bearer secret associated with an application, project, or account. The server checks the key and applies its configured permissions; it usually has no user consent flow.

OAuth is a delegated authorization protocol. An authorization server issues scoped access tokens to a client for a resource owner, with flows such as authorization code plus PKCE for user-facing apps.

OAuth authenticates and authorizes through several roles; it does not make an API secure automatically. Validate token issuer, audience, scope, expiry, and transport.

Side by side

	OAuth	API key
Primary identity	Application or integration	User delegation to a client
Permission scope	Usually key-level or account-level	Explicit scopes and resource audiences
Consent	Configured out of band	Authorization server can obtain user consent
Rotation	Replace and distribute a secret	Short-lived access plus refresh or reauthorization
Revocation	Disable the key	Revoke grant, client, or token
Setup cost	Low	Higher: issuer, redirect, PKCE, key discovery
Delegated access	Poor fit	Core use case
Failure risk	Leaked key grants its configured access	Mis-scoped or misvalidated tokens grant unintended access

Choose OAuth when

One trusted backend integration needs a simple credential
There is no user consent or delegated resource ownership
The key can be stored in a secret manager and rotated safely
A small, fixed permission set is sufficient

Choose API key when

A user grants a third-party client access to selected resources
Tokens need narrow scopes and bounded lifetimes
Many clients or resource servers need independent trust boundaries
The system needs standard authorization-code and refresh workflows

The trade-off in detail

API keys are simple until they are copied into source code, logs, or browser bundles. Issue per integration, restrict permissions and network origin where possible, monitor usage, and make replacement routine.

OAuth moves complexity into an authorization server and token validation. Centralise discovery and policy, test redirect and state handling, and use PKCE for public clients.

Neither credential should be sent in query strings. TLS, secret storage, redaction, rate limits, and audit logs remain required.

Things that are commonly said and are wrong

“OAuth is only login.” OAuth is primarily delegated authorization; OpenID Connect adds an identity layer for login.
“An API key is not a password.” Treat a powerful key as a bearer secret with equivalent leakage impact.
“OAuth tokens are safe because they are short-lived.” A stolen token can still be used during its lifetime; scope and audience limit the blast radius.

Decide it in a real repository

Choosing correctly on a whiteboard and enforcing the choice in code are different skills. Gronex ships broken backend repositories whose tests assert the invariant, not the happy path.

FAQ

Should a public developer API start with API keys?

Often yes for application identification and quota when there is no delegated user access. Add OAuth when clients need to access a user’s resources or permissions must be scoped per grant.

Can OAuth and API keys coexist?

Yes. An API key can identify the client while OAuth authorizes a user grant, but document which credential controls quota and which controls resource access.

Where should an API key be sent?

Use an HTTPS header such as Authorization or a provider-specific header, never a URL query string. Query strings leak into logs, history, and referrers.