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.
The two credential models in one frame
API keys and OAuth tokens solve different authorization problems, and choosing the right one starts with knowing the difference. An API key is a static, long-lived secret that identifies a single caller — typically a machine, a service, or an integration. It is simple, and it works well when one workload talks to your API under a known identity. An OAuth token is an authorization artifact obtained through a flow — typically on behalf of a user, scoped, and short-lived — that lets an application act as a user with the user's consent and only within defined scopes. The deciding question is usually: "Is this a machine talking as itself, or an application acting as a user with the user's consent?"
When an API key is the right answer
Choose an API key when there is no user to delegate from — a server-to-server integration, a batch job, a CI/CD pipeline, or a third-party service that needs a stable identity. API keys are ideal for machine-to-machine traffic because they are simple to issue, easy to scope per workload, and straightforward to rotate and revoke. The discipline that keeps them safe is covered in the API keys best practices guide: scope them narrowly, rotate them, keep them out of source code, and monitor them. For pure machine workloads, an API key is usually simpler and entirely appropriate.
When OAuth is the right answer
Choose OAuth when the request should act on behalf of a user with that user's authorization — for example, an application that reads or manages a user's links after the user signs in, or a third-party app that needs scoped, revocable access to a user's account. OAuth's strengths are consent, scoping, and short-lived tokens that can be revoked independently of any single credential. It also avoids sharing a user's password with the application. The trade-off is complexity: implementing an OAuth flow is more work than issuing a key, but for user-delegated access it is the correct model.
A practical decision guide
In practice the choice falls out of the identity model: machine acting as itself → API key; application acting as a user → OAuth. Where you have both, use both — machine keys for service traffic and OAuth for user-authorized flows. Whichever you choose, apply the same hygiene: scope narrowly, rotate, revoke on suspicion, and monitor usage. Matching the credential model to the identity it represents, and securing it either way, is what keeps your integration both usable and safe.