API Authentication Guide: JWT, OAuth 2.0, API Keys & mTLS

Choosing the right authentication mechanism for your API depends on who the caller is, where tokens are stored, and what security guarantees you need. This guide walks through every major strategy with implementation examples and a comparison table.

JWT: Structure, Validation & Refresh Tokens

A JWT consists of three base64url-encoded parts: header (algorithm), payload (claims), and signature. Validate the signature and claims on every request:

import jwt from 'jsonwebtoken';
import { Request, Response, NextFunction } from 'express';

// Issue tokens — short-lived access + long-lived refresh
function issueTokens(userId: string, roles: string[]) {
  const accessToken = jwt.sign(
    { sub: userId, roles, type: 'access' },
    process.env.JWT_SECRET!,
    { expiresIn: '15m', issuer: 'devplaybook.cc', audience: 'api' }
  );
  const refreshToken = jwt.sign(
    { sub: userId, jti: crypto.randomUUID(), type: 'refresh' },
    process.env.REFRESH_SECRET!,
    { expiresIn: '7d' }
  );
  return { accessToken, refreshToken };
}

// Middleware — validates Bearer token on every protected request
export function requireAuth(req: Request, res: Response, next: NextFunction) {
  const token = req.headers.authorization?.replace('Bearer ', '');
  if (!token) return res.status(401).json({ error: 'Missing token' });

  try {
    const payload = jwt.verify(token, process.env.JWT_SECRET!, {
      issuer: 'devplaybook.cc',
      audience: 'api',
    }) as any;

    if (payload.type !== 'access') throw new Error('Wrong token type');
    req.user = { id: payload.sub, roles: payload.roles };
    next();
  } catch (err) {
    res.status(401).json({ error: 'Invalid or expired token' });
  }
}

OAuth 2.0 Client Credentials Flow (M2M)

For machine-to-machine authentication (background jobs, microservices), use the OAuth 2.0 Client Credentials grant — no user involved:

# Step 1: Client requests access token using client_id + client_secret
POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=svc-orders
&client_secret=cs_live_abc123
&scope=users:read orders:write

# Step 2: Authorization server responds with short-lived access token
{
  "access_token": "eyJhbGci...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "users:read orders:write"
}

# Step 3: Service uses the token as Bearer in API calls
GET /api/v1/users
Authorization: Bearer eyJhbGci...

# Client implementation — cache token, refresh before expiry
class OAuth2Client {
  private token: string | null = null;
  private expiresAt = 0;

  async getToken(): Promise<string> {
    if (this.token && Date.now() < this.expiresAt - 30_000) return this.token;
    const res = await fetch(process.env.TOKEN_URL!, {
      method: 'POST',
      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
      body: new URLSearchParams({ grant_type: 'client_credentials',
        client_id: process.env.CLIENT_ID!, client_secret: process.env.CLIENT_SECRET!,
        scope: 'users:read' }),
    });
    const data = await res.json();
    this.token = data.access_token;
    this.expiresAt = Date.now() + data.expires_in * 1000;
    return this.token!;
  }
}

mTLS: Mutual TLS for Service-to-Service

mTLS requires both client and server to present certificates. Zero tokens to manage — the TLS handshake IS the authentication:

import https from 'https';
import fs from 'fs';

// Server: require client certificates
const serverOptions = {
  key: fs.readFileSync('./certs/server.key'),
  cert: fs.readFileSync('./certs/server.crt'),
  ca: fs.readFileSync('./certs/ca.crt'),   // CA that issued client certs
  requestCert: true,    // Request client cert
  rejectUnauthorized: true,  // Reject if cert is invalid
};

https.createServer(serverOptions, app).listen(8443);

// In Express middleware — extract client identity from cert
app.use((req: any, res, next) => {
  const cert = req.socket.getPeerCertificate();
  if (!cert.subject) return res.status(401).send('Client cert required');
  req.serviceId = cert.subject.CN;  // e.g. 'orders-service'
  next();
});

# Client: present its own certificate when calling the server
# curl --cert client.crt --key client.key --cacert ca.crt https://api:8443/endpoint

Authentication Method Comparison