API Authentication: OAuth, JWT, and Beyond

API authentication determines who can access your service and what they're allowed to do. Getting it wrong exposes user data, enables account takeovers, and creates compliance violations. This guide covers the authentication mechanisms used in modern APIs, when to use each, and how to implement them securely.

OAuth 2.0 Flows

OAuth 2.0 is an authorization framework that lets applications access resources on behalf of users without handling their passwords. Different flows suit different application types.

Authorization Code Flow

The standard flow for server-side web applications. The client redirects the user to the authorization server, which returns an authorization code that the client exchanges for tokens.

1. User clicks "Login with GitHub"
2. App redirects to: https://github.com/login/oauth/authorize?
     client_id=abc123&
     redirect_uri=https://myapp.com/callback&
     scope=user:email&
     state=random-csrf-token

3. User authenticates and approves access
4. GitHub redirects to: https://myapp.com/callback?code=xyz789&state=random-csrf-token

5. App server exchanges the code for tokens:

# Server-side token exchange
async def oauth_callback(request):
    code = request.query_params['code']
    state = request.query_params['state']

    # Verify state matches what we stored in the session
    if state != request.session['oauth_state']:
        raise HTTPException(status_code=400, detail="Invalid state parameter")

    # Exchange code for tokens (server-to-server, client_secret never exposed)
    token_response = await httpx.post(
        'https://github.com/login/oauth/access_token',
        json={
            'client_id': settings.GITHUB_CLIENT_ID,
            'client_secret': settings.GITHUB_CLIENT_SECRET,
            'code': code,
            'redirect_uri': settings.REDIRECT_URI,
        },
        headers={'Accept': 'application/json'},
    )

    tokens = token_response.json()
    access_token = tokens['access_token']
    # Store token securely and create a session for the user

The authorization code never reaches the browser's URL bar for long, and the client secret stays on the server.

Authorization Code Flow with PKCE

PKCE (Proof Key for Code Exchange) protects against authorization code interception, making the flow safe for public clients like single-page applications and mobile apps that cannot securely store a client secret.

// Generate PKCE challenge
function generateCodeVerifier(): string {
  const array = new Uint8Array(32);
  crypto.getRandomValues(array);
  return base64URLEncode(array);
}

async function generateCodeChallenge(verifier: string): Promise<string> {
  const hash = await crypto.subtle.digest(
    'SHA-256',
    new TextEncoder().encode(verifier)
  );
  return base64URLEncode(new Uint8Array(hash));
}

// Step 1: Generate and store verifier
const codeVerifier = generateCodeVerifier();
sessionStorage.setItem('code_verifier', codeVerifier);
const codeChallenge = await generateCodeChallenge(codeVerifier);

// Step 2: Redirect with challenge
const authUrl = new URL('https://auth.example.com/authorize');
authUrl.searchParams.set('client_id', CLIENT_ID);
authUrl.searchParams.set('redirect_uri', REDIRECT_URI);
authUrl.searchParams.set('response_type', 'code');
authUrl.searchParams.set('code_challenge', codeChallenge);
authUrl.searchParams.set('code_challenge_method', 'S256');
window.location.href = authUrl.toString();

// Step 3: Exchange code with verifier
const tokenResponse = await fetch('https://auth.example.com/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'authorization_code',
    code: authorizationCode,
    redirect_uri: REDIRECT_URI,
    client_id: CLIENT_ID,
    code_verifier: sessionStorage.getItem('code_verifier'),
  }),
});

PKCE should be used for all public clients. The current OAuth 2.1 draft recommends PKCE for all clients, including confidential ones.

Client Credentials Flow

For machine-to-machine communication where no user is involved. The client authenticates directly with its own credentials:

# Service-to-service authentication
token_response = await httpx.post(
    'https://auth.example.com/token',
    data={
        'grant_type': 'client_credentials',
        'client_id': settings.SERVICE_CLIENT_ID,
        'client_secret': settings.SERVICE_CLIENT_SECRET,
        'scope': 'api:read api:write',
    },
)

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

JWT Structure and Validation

JSON Web Tokens encode claims as a signed, base64-encoded payload. A JWT has three parts: header, payload, and signature.

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.    # Header
eyJzdWIiOiJ1c2VyLTEyMyIsImV4cCI6MTcwMH0.  # Payload
SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw  # Signature

Decoded payload:

{
  "sub": "user-123",
  "iss": "https://auth.example.com",
  "aud": "https://api.example.com",
  "exp": 1700000000,
  "iat": 1699996400,
  "scope": "read write"
}

Proper JWT validation must check:

import jwt from 'jsonwebtoken';
import jwksClient from 'jwks-rsa';

const client = jwksClient({
  jwksUri: 'https://auth.example.com/.well-known/jwks.json',
  cache: true,
  rateLimit: true,
});

async function validateToken(token: string): Promise<JWTPayload> {
  const decoded = jwt.decode(token, { complete: true });
  if (!decoded) throw new Error('Invalid token format');

  // Fetch the signing key
  const key = await client.getSigningKey(decoded.header.kid);
  const publicKey = key.getPublicKey();

  // Verify signature, expiration, issuer, and audience
  const payload = jwt.verify(token, publicKey, {
    algorithms: ['RS256'],            // Reject 'none' and symmetric algorithms
    issuer: 'https://auth.example.com',
    audience: 'https://api.example.com',
    clockTolerance: 30,               // 30 seconds of clock skew allowed
  }) as JWTPayload;

  return payload;
}

Critical JWT security rules:

• Always validate the signature. Never trust an unverified JWT.
• Restrict allowed algorithms. Specify exactly which algorithms you accept. The alg: "none" attack exploits libraries that accept unsigned tokens.
• Validate issuer and audience. A token issued by a different service or intended for a different API should be rejected.
• Use asymmetric keys (RS256 or ES256). The authorization server signs with a private key; API servers verify with the public key. No shared secrets.

API Keys Best Practices

API keys identify the calling application rather than a user. They work well for server-to-server calls, rate limiting, and usage tracking.

# API key in header (preferred)
curl -H "X-API-Key: sk_live_abc123def456" https://api.example.com/data

# Never in URL (logged in access logs, browser history, referrer headers)
# Bad: https://api.example.com/data?api_key=sk_live_abc123def456

API key best practices:

• Prefix keys to identify their type and environment: sk_live_, sk_test_, pk_live_.
• Hash keys in storage. Store SHA-256(key) in your database, not the plaintext key. Show the key once at creation, then never again.
• Scope keys narrowly. Each key should grant minimal permissions.
• Support rotation. Allow multiple active keys per account so clients can rotate without downtime.

Mutual TLS (mTLS)

mTLS requires both client and server to present certificates during the TLS handshake. This provides strong authentication for service-to-service communication without application-level tokens.

# Python client with mTLS
import httpx

client = httpx.Client(
    cert=('/path/to/client.crt', '/path/to/client.key'),
    verify='/path/to/ca-bundle.crt',
)

response = client.get('https://internal-api.example.com/data')

mTLS is standard in service meshes (Istio, Linkerd) where the mesh automatically manages certificate issuance, rotation, and verification. For direct implementation, use a certificate authority like Vault's PKI backend.

Token Refresh Patterns

Access tokens should be short-lived (5-15 minutes). Refresh tokens obtain new access tokens without requiring the user to re-authenticate:

async function fetchWithAuth(url: string, options: RequestInit = {}): Promise<Response> {
  let accessToken = tokenStore.getAccessToken();

  // Check if token is about to expire (within 60 seconds)
  if (isTokenExpiringSoon(accessToken, 60)) {
    accessToken = await refreshAccessToken();
  }

  const response = await fetch(url, {
    ...options,
    headers: {
      ...options.headers,
      Authorization: `Bearer ${accessToken}`,
    },
  });

  // Handle token expiration during request
  if (response.status === 401) {
    accessToken = await refreshAccessToken();
    return fetch(url, {
      ...options,
      headers: { ...options.headers, Authorization: `Bearer ${accessToken}` },
    });
  }

  return response;
}

async function refreshAccessToken(): Promise<string> {
  const response = await fetch('https://auth.example.com/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'refresh_token',
      refresh_token: tokenStore.getRefreshToken(),
      client_id: CLIENT_ID,
    }),
  });

  const tokens = await response.json();
  tokenStore.setTokens(tokens.access_token, tokens.refresh_token);
  return tokens.access_token;
}

Refresh token security:

• Rotate refresh tokens. Issue a new refresh token with each use. If a refresh token is used twice, assume it was stolen and revoke the entire token family.
• Bind to the client. For confidential clients, require client authentication when refreshing.
• Set absolute expiration. Refresh tokens should expire eventually (days to weeks), forcing periodic re-authentication.

Authentication is the foundation of API security. Use OAuth 2.0 with PKCE for user-facing applications, client credentials for service-to-service calls, and mTLS for internal service meshes. Always validate JWTs fully, never roll your own cryptography, and assume that any token will eventually be stolen, so design your refresh and revocation mechanisms accordingly.