Every API needs authentication. The question is which method fits your use case. API keys, OAuth 2.0, and JWTs each solve different problems, and understanding the tradeoffs saves you from retrofitting auth later.

This guide breaks down all three, shows how they work in practice, and explains when to combine them.

API Keys — Simple Shared Secrets

An API key is a unique string the server generates and the client sends with every request. There’s no user context, no token exchange — just a secret that identifies the caller.

How It Works

1. The server generates a key and gives it to the client (usually through a dashboard).
2. The client includes the key in every request, typically as a header.
3. The server looks up the key, checks permissions, and processes the request.

Code Example

curl -H "X-API-Key: sk_live_abc123def456" \
  https://api.example.com/v1/data

Server-side validation:

def authenticate(request):
    key = request.headers.get("X-API-Key")
    client = db.api_keys.find_one({"key": hash(key), "active": True})
    if not client:
        raise Unauthorized("Invalid API key")
    return client

When to Use

• Server-to-server communication where no user is involved
• Internal microservices behind a firewall
• Third-party integrations with rate limiting per client (think Stripe, OpenAI)

Security Considerations

• Always transmit over HTTPS/TLS — keys in plaintext are trivially intercepted
• Store keys hashed on the server, never in plain text
• Rotate keys on a schedule and support multiple active keys during transitions
• Never embed keys in client-side code or public repos — see our guide on securing AI API keys

API keys are the workhorse of machine-to-machine auth. They fall short when you need to act on behalf of a user.

OAuth 2.0 — Delegated Authorization

OAuth 2.0 lets a user grant a third-party app limited access to their resources without sharing their password. It’s the protocol behind “Sign in with Google” and every app that asks to access your GitHub repos.

How It Works

1. The client redirects the user to the authorization server.
2. The user logs in and consents to the requested scopes.
3. The authorization server redirects back with an authorization code.
4. The client exchanges the code for an access token (and optionally a refresh token).
5. The client uses the access token to call the resource API.

For a deeper walkthrough, see How OAuth Actually Works.

Code Example

Token exchange (Authorization Code flow):

import requests

token_response = requests.post("https://auth.example.com/oauth/token", data={
    "grant_type": "authorization_code",
    "code": "AUTH_CODE_FROM_REDIRECT",
    "client_id": "your_client_id",
    "client_secret": "your_client_secret",
    "redirect_uri": "https://yourapp.com/callback"
})

access_token = token_response.json()["access_token"]

# Use the token
api_response = requests.get("https://api.example.com/v1/user/repos",
    headers={"Authorization": f"Bearer {access_token}"}
)

When to Use

• Any time a user grants your app access to their data on another service
• Third-party app ecosystems and marketplace integrations
• Mobile and single-page apps that need user-scoped access

Security Considerations

• Always use the Authorization Code flow with PKCE — the implicit flow is deprecated
• Store client secrets server-side only
• Keep access tokens short-lived (minutes) and use refresh tokens for longevity
• Validate redirect URIs strictly to prevent authorization code interception

OAuth handles delegation well but says nothing about the token format. That’s where JWT comes in.

JWT — Stateless, Self-Contained Tokens

A JSON Web Token (JWT) is a signed, base64-encoded JSON object that carries claims about the user. The server can verify it without hitting a database, making it ideal for distributed systems.

For the full specification breakdown, see What Is JWT and How JWT Actually Works.

How It Works

1. The user authenticates (via login form, OAuth, etc.).
2. The server creates a JWT containing user claims, signs it with a secret or private key, and returns it.
3. The client sends the JWT in the Authorization header on subsequent requests.
4. The server verifies the signature and reads the claims — no database lookup needed.

Code Example

Issuing and verifying a JWT:

import jwt
from datetime import datetime, timedelta

SECRET = "your-signing-secret"

# Issue
payload = {
    "sub": "user_42",
    "role": "admin",
    "exp": datetime.utcnow() + timedelta(minutes=15)
}
token = jwt.encode(payload, SECRET, algorithm="HS256")

# Verify
try:
    claims = jwt.decode(token, SECRET, algorithms=["HS256"])
    print(claims["sub"])  # "user_42"
except jwt.ExpiredSignatureError:
    print("Token expired")

When to Use

• Stateless authentication across multiple services or microservices
• When you need to embed user roles, permissions, or metadata in the token itself
• Short-lived access tokens in OAuth flows

Security Considerations

• Always verify the signature and the exp claim — never trust an unverified token
• Use asymmetric keys (RS256/ES256) when multiple services need to verify tokens
• Keep payloads small — JWTs are sent with every request
• JWTs can’t be revoked individually without a blocklist; keep expiry times short

Combining Them — The Real-World Pattern

In production, these methods rarely exist in isolation. The most common pattern:

• OAuth issues JWTs: The OAuth authorization server returns a JWT as the access token. You get delegated auth and stateless verification.
• API keys for services, JWTs for users: Backend services authenticate with API keys. User-facing requests carry JWTs. The API gateway routes accordingly.

User → [JWT in header] → API Gateway → Microservice
Service → [API Key in header] → API Gateway → Microservice

This layered approach follows the principle of least privilege — each caller gets exactly the auth mechanism that fits its trust level. For broader patterns, see our API design best practices guide.

Comparison Table

Feature	API Keys	OAuth 2.0	JWT
Complexity	Low	High	Medium
User context	No	Yes	Yes
Stateless	No (server lookup)	Depends on token format	Yes
Delegation	No	Yes	No
Revocation	Instant (delete key)	Instant (revoke token)	Requires blocklist or expiry
Best for	Server-to-server, internal APIs	Third-party apps, user consent flows	Microservices, stateless APIs
Token format	Opaque string	Any (often JWT)	Signed JSON

Which Should You Pick?

• Just need to identify a caller with no user involved? API key. It’s the simplest path and works well for internal services and third-party integrations.
• Users granting access to their data? OAuth 2.0. There’s no substitute for delegated authorization.
• Distributed services that need to verify identity without shared state? JWT. Embed claims, verify locally, skip the database round-trip.
• Building a production API platform? Combine all three. OAuth for the auth flow, JWTs as the token format, and API keys for service-level access.

There’s no single “best” method — only the right one for your architecture. Start with the simplest approach that meets your security requirements, and layer on complexity only when the use case demands it.