harsh040506/api-authentication

API Authentication

Production-ready patterns for authenticating and authorizing API consumers.

---

Authentication vs Authorization

Authentication (AuthN) — Who are you?
  → Verify identity using a credential (password, token, certificate)
  → "You are [email protected]"

Authorization (AuthZ) — What can you do?
  → Enforce permissions for the verified identity
  → "alice can read orders but not refund them"

Both must be present. Authentication without authorization is incomplete.

---

Choosing an Auth Strategy

| Use case | Recommended | Why | |----------|-------------|-----| | Browser SPA + first-party API | HttpOnly cookies | XSS-safe; CSRF mitigable | | Mobile app + first-party API | JWT in secure storage | No cookie jar on mobile | | Server-to-server (machine) | OAuth 2.0 Client Credentials | No user involved | | Third-party API consumers | API keys | Simple, revocable, auditable | | "Login with Google/GitHub" | OAuth 2.0 Authorization Code + PKCE | Delegates identity to provider | | Legacy / simple internal | Session + server-side store | Simple, fully revocable |

---

JWT (JSON Web Token)

Structure

header.payload.signature

eyJhbGciOiJIUzI1NiJ9  ←  Base64({"alg":"HS256","typ":"JWT"})
.
eyJ1c2VyX2lkIjoiYWJjIn0  ←  Base64({"user_id":"abc","exp":1234567890,"iat":1234567800})
.
SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c  ←  HMAC-SHA256(header.payload, secret)

Signing and Verifying (Node.js)

import jwt from 'jsonwebtoken';

const JWT_SECRET = process.env.JWT_SECRET!;           // At least 256 bits of entropy
const JWT_ALGORITHM = 'HS256' as const;               // Always specify — never trust header's alg
const ACCESS_TOKEN_TTL = 15 * 60;                     // 15 minutes
const REFRESH_TOKEN_TTL = 7 * 24 * 60 * 60;          // 7 days

interface JWTPayload {
  sub: string;     // Subject (user ID) — standard claim
  iat: number;     // Issued at — standard claim
  exp: number;     // Expiry — standard claim
  jti: string;     // JWT ID — unique per token (enables revocation)
  roles: string[]; // Custom claim
}

function signAccessToken(userId: string, roles: string[]): string {
  return jwt.sign(
    { sub: userId, roles, jti: crypto.randomUUID() },
    JWT_SECRET,
    { algorithm: JWT_ALGORITHM, expiresIn: ACCESS_TOKEN_TTL }
  );
}

function verifyToken(token: string): JWTPayload {
  // MUST pass algorithms array — prevents algorithm confusion attacks
  return jwt.verify(token, JWT_SECRET, {
    algorithms: [JWT_ALGORITHM],
  }) as JWTPayload;
}

// Middleware
function requireAuth(req: Request, res: Response, next: NextFunction) {
  const header = req.headers.authorization;
  if (!header?.startsWith('Bearer ')) {
    return res.status(401).json({ error: { code: 'MISSING_TOKEN' } });
  }
  
  try {
    const payload = verifyToken(header.slice(7));
    req.user = { id: payload.sub, roles: payload.roles };
    next();
  } catch (err) {
    if (err instanceof jwt.TokenExpiredError) {
      return res.status(401).json({ error: { code: 'TOKEN_EXPIRED' } });
    }
    return res.status(401).json({ error: { code: 'INVALID_TOKEN' } });
  }
}

Critical Security Rules

✓ Always specify algorithm in verify() call (prevents alg:none attacks)
✓ Use asymmetric keys (RS256/ES256) when multiple services verify tokens
✓ Keep access token TTL short (15 min). Use refresh tokens for longevity
✓ Include jti (JWT ID) for revocation capability
✓ Never put sensitive data in payload (it's base64, not encrypted)
✓ Validate iss (issuer) and aud (audience) claims for multi-service setups
✗ Never trust the alg field from the token header
✗ Never use alg:none
✗ Never store JWT secret in code — use environment variable

---

Refresh Token Rotation

Short access tokens (15 min) + long refresh tokens (7 days) = good security/UX balance.

// Store refresh tokens in database (allows revocation)
interface RefreshToken {
  id: string;          // The actual token (random, opaque — not a JWT)
  userId: string;
  expiresAt: Date;
  revokedAt: Date | null;
  replacedByTokenId: string | null;  // Track rotation chain
  createdAt: Date;
}

async function refreshAccessToken(refreshToken: string) {
  // Look up the refresh token
  const storedToken = await db.refreshTokens.findUnique({
    where: { id: refreshToken },
  });
  
  // Validate
  if (!storedToken) throw new UnauthorizedError('INVALID_REFRESH_TOKEN');
  if (storedToken.revokedAt) {
    // Refresh token reuse detected — revoke entire family (security event)
    await db.refreshTokens.revokeFamily(storedToken.userId);
    throw new UnauthorizedError('REFRESH_TOKEN_REUSE');  // Possible token theft
  }
  if (storedToken.expiresAt < new Date()) {
    throw new UnauthorizedError('REFRESH_TOKEN_EXPIRED');
  }
  
  // Rotate: revoke old, issue new
  const newRefreshToken = crypto.randomUUID() + crypto.randomUUID();
  
  await db.$transaction([
    db.refreshTokens.update({
      where: { id: refreshToken },
      data: { revokedAt: new Date(), replacedByTokenId: newRefreshToken },
    }),
    db.refreshTokens.create({
      data: {
        id: newRefreshToken,
        userId: storedToken.userId,
        expiresAt: new Date(Date.now() + REFRESH_TOKEN_TTL * 1000),
      },
    }),
  ]);
  
  const user = await db.users.findById(storedToken.userId);
  return {
    accessToken: signAccessToken(user.id, user.roles),
    refreshToken: newRefreshToken,
  };
}

---

HttpOnly Cookie Auth (Browser SPAs)

Preferred over localStorage for browser applications — immune to XSS token theft.

// Set tokens as HttpOnly cookies on login
res.cookie('access_token', accessToken, {
  httpOnly: true,          // Not accessible from JavaScript
  secure: true,            // HTTPS only
  sameSite: 'lax',         // CSRF protection for most cases
  maxAge: ACCESS_TOKEN_TTL * 1000,
  path: '/',
});

res.cookie('refresh_token', refreshToken, {
  httpOnly: true,
  secure: true,
  sameSite: 'lax',
  maxAge: REFRESH_TOKEN_TTL * 1000,
  path: '/api/auth/refresh',  // Scope to refresh endpoint only
});

// Read from cookie in middleware
function requireAuth(req: Request, res: Response, next: NextFunction) {
  const token = req.cookies.access_token;  // parse via cookie-parser
  if (!token) return res.status(401).json({ error: { code: 'MISSING_TOKEN' } });
  // ... verify as before
}

// Logout — clear both cookies
app.post('/api/auth/logout', requireAuth, async (req, res) => {
  await db.refreshTokens.revoke(req.cookies.refresh_token);
  
  res.clearCookie('access_token',  { httpOnly: true, secure: true, sameSite: 'lax' });
  res.clearCookie('refresh_token', { httpOnly: true, secure: true, sameSite: 'lax', path: '/api/auth/refresh' });
  
  res.status(204).end();
});

CSRF with cookies: Use sameSite: 'lax' for most apps. For sameSite: 'none' (cross-site), add a CSRF token (double-submit cookie or synchronizer token pattern).

---

API Keys

For third-party developers, service accounts, or CI/CD integrations.

// Key format: prefix + random bytes (prefix helps with secret scanning)
// Example: "myapp_sk_live_aBcDeFgH1234567890ABCDEF"
function generateApiKey(prefix = 'sk_live'): { key: string; hash: string } {
  const random = crypto.randomBytes(32).toString('base64url');
  const key = `myapp_${prefix}_${random}`;
  // Store hash of the key, never the key itself
  const hash = crypto.createHash('sha256').update(key).digest('hex');
  return { key, hash };
}

// On creation: return key to user (shown only once), store hash
const { key, hash } = generateApiKey();
await db.apiKeys.create({ data: { keyHash: hash, userId, name, scopes } });
return { apiKey: key }; // Show to user now; never show again

// On verification: hash the presented key and compare
async function verifyApiKey(presentedKey: string) {
  const hash = crypto.createHash('sha256').update(presentedKey).digest('hex');
  const apiKey = await db.apiKeys.findUnique({ 
    where: { keyHash: hash },
    include: { user: true },
  });
  if (!apiKey || apiKey.revokedAt) throw new UnauthorizedError('INVALID_API_KEY');
  
  // Update last used (async, don't block request)
  db.apiKeys.update({ where: { keyHash: hash }, data: { lastUsedAt: new Date() } });
  
  return apiKey;
}

---

OAuth 2.0 Authorization Code + PKCE

For "Login with Google/GitHub/etc." or exposing your API to third-party apps.

// PKCE (Proof Key for Code Exchange) — required for public clients
function generatePKCE() {
  const verifier = crypto.randomBytes(32).toString('base64url');
  const challenge = crypto.createHash('sha256').update(verifier).digest('base64url');
  return { verifier, challenge };
}

// Step 1: Redirect to provider
app.get('/auth/github', (req, res) => {
  const { verifier, challenge } = generatePKCE();
  const state = crypto.randomBytes(16).toString('hex');  // CSRF prevention
  
  // Store verifier + state in server-side session (not cookie)
  req.session.pkceVerifier = verifier;
  req.session.oauthState = state;
  
  const params = new URLSearchParams({
    client_id: process.env.GITHUB_CLIENT_ID!,
    redirect_uri: 'https://app.example.com/auth/github/callback',
    scope: 'read:user user:email',
    state,
    code_challenge: challenge,
    code_challenge_method: 'S256',
  });
  
  res.redirect(`https://github.com/login/oauth/authorize?${params}`);
});

// Step 2: Handle callback
app.get('/auth/github/callback', async (req, res) => {
  const { code, state } = req.query;
  
  // Validate state (CSRF check)
  if (state !== req.session.oauthState) {
    return res.status(400).json({ error: { code: 'INVALID_STATE' } });
  }
  
  // Exchange code for token
  const tokenResponse = await fetch('https://github.com/login/oauth/access_token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
    body: JSON.stringify({
      client_id: process.env.GITHUB_CLIENT_ID!,
      client_secret: process.env.GITHUB_CLIENT_SECRET!,
      code,
      code_verifier: req.session.pkceVerifier,  // PKCE verification
    }),
  });
  
  const { access_token } = await tokenResponse.json();
  
  // Fetch user profile
  const profile = await fetchGitHubProfile(access_token);
  
  // Find or create user in your DB
  const user = await findOrCreateUser({ email: profile.email, githubId: profile.id });
  
  // Issue your own session/tokens
  issueSessionCookies(res, user);
  res.redirect('/dashboard');
});

---

Role-Based Authorization (RBAC)

// Define roles and permissions
const PERMISSIONS = {
  'orders:read':   ['customer', 'support', 'manager', 'admin'],
  'orders:write':  ['manager', 'admin'],
  'orders:refund': ['manager', 'admin'],
  'users:read':    ['support', 'manager', 'admin'],
  'users:write':   ['admin'],
} as const;

type Permission = keyof typeof PERMISSIONS;

// Authorization middleware factory
function requirePermission(permission: Permission) {
  return (req: Request, res: Response, next: NextFunction) => {
    const userRoles = req.user?.roles ?? [];
    const allowedRoles = PERMISSIONS[permission];
    
    if (!userRoles.some(role => allowedRoles.includes(role as any))) {
      // Log the authorization failure
      logger.warn({
        user_id: req.user?.id,
        required_permission: permission,
        user_roles: userRoles,
        path: req.path,
      }, 'Authorization denied');
      
      return res.status(403).json({
        error: { code: 'FORBIDDEN', message: 'Insufficient permissions' }
      });
    }
    
    next();
  };
}

// Usage
app.post('/orders/:id/refund', requireAuth, requirePermission('orders:refund'), refundHandler);

Resource-Level Authorization (IDOR Prevention)

// Always verify ownership, not just authentication
app.get('/orders/:id', requireAuth, async (req, res) => {
  const order = await db.orders.findById(req.params.id);
  
  if (!order) return res.status(404).json({ error: { code: 'NOT_FOUND' } });
  
  // Critical: check this user owns this resource
  // Admins and support may bypass ownership check
  const canView = order.customerId === req.user.id 
    || req.user.roles.some(r => ['admin', 'support'].includes(r));
    
  if (!canView) {
    // Return 404 not 403 — don't confirm the order exists for other users
    return res.status(404).json({ error: { code: 'NOT_FOUND' } });
  }
  
  res.json(order);
});

---

Security Headers for APIs

import helmet from 'helmet';

app.use(helmet({
  contentSecurityPolicy: false,     // Handled separately if API + SPA
  crossOriginEmbedderPolicy: false, // API consumers need flexibility
}));

// Explicit security headers
app.use((req, res, next) => {
  res.setHeader('X-Content-Type-Options', 'nosniff');
  res.setHeader('X-Frame-Options', 'DENY');
  res.setHeader('Referrer-Policy', 'strict-origin-when-cross-origin');
  // HSTS — only for HTTPS
  res.setHeader('Strict-Transport-Security', 'max-age=31536000; includeSubDomains');
  next();
});

// CORS — never use wildcard for authenticated APIs
app.use(cors({
  origin: (origin, callback) => {
    const allowed = ['https://app.example.com', 'https://admin.example.com'];
    if (!origin || allowed.includes(origin)) {
      callback(null, true);
    } else {
      callback(new Error('Not allowed by CORS'));
    }
  },
  credentials: true,  // Required for cookie-based auth
  methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
  allowedHeaders: ['Content-Type', 'Authorization', 'Idempotency-Key'],
}));

Deeper Reference

For complete token implementation patterns and OAuth flow diagrams, see:

• references/token-patterns.md — JWT schema design, RS256 key rotation, JWKS endpoints, refresh token rotation algorithm, and opaque token patterns
• references/oauth-flows.md — Authorization Code + PKCE, Client Credentials, Device Authorization flows with sequence diagrams and common mistake tables