API Keys vs OAuth Tokens: When to Use Which
Both an API key and an OAuth token let a client prove who it is. But they answer to different actors, live different lifetimes, and grant access differently. Reach for the wrong one and you either hand out a credential that's too powerful for too long, or you build a heavy OAuth flow where a simple key would do.
This guide lays out the mental model: API keys for machines, OAuth for humans (and delegated access). Here's how to decide in practice.
The core distinction
| API Key | OAuth Token | |
|---|---|---|
| Represents | A client/application | A user's delegated permission |
| Lifetime | Long-lived (until rotated) | Short-lived + refreshable |
| Scopes | Fixed, coarse | Fine-grained, per-grant |
| Revocation | Manual (rotate/delete) | Instant, per-token |
| Typical use | Server-to-server | "Log in with X", third-party app access |
| Flow | Simple header | Multi-step authorization flow |
The decision hinges on who the credential represents and how long it should live.
When to use an API key
Use an API key when the access is machine-to-machine and you're fine with a long-lived, coarse credential:
- Automation / cron jobs that hit your API on a schedule.
- Integrations where one server talks to another on behalf of your app.
- CLI tools and scripts.
- Backend services that need a stable credential.
API keys are simple: generate one, store it, send it as a Bearer token. They're
right when you own the client and don't need to delegate a user's permissions
per-request.
The trade-offs to manage:
- Long lifetime — a leaked key stays valid until you rotate it. So: store hashed, rotate on a schedule, and restrict scopes.
- Coarse scopes — an API key usually has a fixed scope, so make the scope
minimal (e.g.
links:readonly where you don't need writes).
When to use OAuth
Use OAuth when a user needs to grant access, or when you need short-lived, fine-grained, revocable credentials:
- "Log in with Google/GitHub/Apple" — third-party identity, delegated on the user's behalf.
- Third-party apps that need to act as a user with the user's consent.
- Scoped, short-lived access where a leaked token is a small, bounded risk.
OAuth's value is delegation and revocation: a token is issued for a specific user + scope, expires quickly, and can be revoked instantly if the user logs out or revokes the app. That's exactly the model for human-facing access.
The cost: OAuth is a multi-step flow (authorize → callback → token) and more moving parts to secure.
The grey area: when both could work
Some cases sit between the two:
- An API key with scopes (like yas.sh's scoped API keys) — you can give a machine key read-only or write-only access. This keeps the simplicity of a key while limiting blast radius.
- OAuth with machine credentials (client credentials grant) — lets a server get a short-lived token without a user. Useful when you want the short-lived, revocable properties of OAuth for a service.
The rule of thumb: if you want simple, long-lived, owned-by-you → API key. If you want delegated, short-lived, user-scoped → OAuth. If you want short-lived for a service, look at the client-credentials OAuth grant.
A practical decision helper
Ask two questions:
- Who is acting? A machine you control (API key) or a user granting access (OAuth)?
- How long should it live? Indefinitely with rotation (API key) or short with auto-refresh and instant revocation (OAuth)?
Answer "machine + long-lived" → API key. "user + short-lived/revocable" → OAuth. "machine but short-lived" → consider scoped API keys or client-credentials OAuth.
The takeaway
API keys and OAuth tokens aren't interchangeable — they're for different actors and lifetimes. Use API keys for your own machine automation with minimal fixed scopes, and OAuth when a user needs to delegate access with short-lived, revocable tokens. Match the credential type to who's acting and how long it should live, and you avoid both over-privileged long-lived secrets and over-engineered flows.
On yas.sh, you get both: scoped API keys for server automation, and OAuth (Google, GitHub, Apple) for sign-in — so the right tool is there for each case.