API Authentication Best Practices: API Keys, JWT & OAuth Compared

const crypto = require('crypto');

// Generate API key
function generateApiKey() {
  return 'sk_' + crypto.randomBytes(32).toString('base64url');
}
// Result: "sk_ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnop"
// Prefix "sk_" helps identify key type in logs and grep

// Store hashed — never store plain API keys
const bcrypt = require('bcrypt');

async function createApiKey(userId, name) {
  const rawKey = generateApiKey();
  const keyHash = await bcrypt.hash(rawKey, 12);
  const keyPrefix = rawKey.slice(0, 10); // "sk_ABCDEFG" — for display

  await db.apiKeys.create({
    userId,
    name,
    keyHash,
    keyPrefix, // show last-used display in dashboard
    createdAt: new Date(),
    lastUsedAt: null,
    scopes: ['read'] // default minimal scope
  });

  return rawKey; // show ONCE to user, never again
}

# CORRECT
curl -H "Authorization: Bearer sk_your_api_key" https://api.yourapp.com/data

# WRONG — URL ends up in access logs, browser history, Referer headers
curl "https://api.yourapp.com/data?api_key=sk_your_api_key"

// Verification middleware
async function apiKeyAuth(req, res, next) {
  const authHeader = req.headers.authorization;
  if (!authHeader?.startsWith('Bearer ')) {
    return res.status(401).json({ error: 'Missing API key' });
  }

  const rawKey = authHeader.slice(7);
  const prefix = rawKey.slice(0, 10);

  // Look up by prefix (fast), then verify full hash
  const keyRecord = await db.apiKeys.findByPrefix(prefix);
  if (!keyRecord) return res.status(401).json({ error: 'Invalid API key' });

  const valid = await bcrypt.compare(rawKey, keyRecord.keyHash);
  if (!valid) return res.status(401).json({ error: 'Invalid API key' });

  // Update last used
  await db.apiKeys.update(keyRecord.id, { lastUsedAt: new Date() });

  req.apiKey = keyRecord;
  req.userId = keyRecord.userId;
  next();
}

const redis = require('redis');

async function rateLimitByApiKey(apiKeyId, limit, windowSeconds) {
  const key = `ratelimit:key:${apiKeyId}`;
  const count = await redis.incr(key);
  if (count === 1) await redis.expire(key, windowSeconds);
  
  const remaining = Math.max(0, limit - count);
  return { allowed: count <= limit, remaining, limit };
}

app.use(async (req, res, next) => {
  if (!req.apiKey) return next();
  
  const { allowed, remaining, limit } = await rateLimitByApiKey(
    req.apiKey.id, 1000, 3600 // 1000 requests/hour
  );
  
  res.setHeader('X-RateLimit-Limit', limit);
  res.setHeader('X-RateLimit-Remaining', remaining);
  
  if (!allowed) return res.status(429).json({ error: 'Rate limit exceeded' });
  next();
});

# FastAPI — JWT authentication dependency
from fastapi import Depends, HTTPException, status
from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
import jwt

security = HTTPBearer()

async def get_current_user(
    credentials: HTTPAuthorizationCredentials = Depends(security)
):
    token = credentials.credentials
    try:
        payload = jwt.decode(
            token,
            PUBLIC_KEY,
            algorithms=["RS256"],
            audience="api.yourapp.com",
            issuer="auth.yourapp.com"
        )
    except jwt.ExpiredSignatureError:
        raise HTTPException(status_code=401, detail="Token expired")
    except jwt.InvalidTokenError:
        raise HTTPException(status_code=401, detail="Invalid token")
    
    return payload

@app.get("/api/profile")
async def get_profile(user=Depends(get_current_user)):
    return {"userId": user["sub"], "email": user["email"]}

// Define available scopes
const SCOPES = {
  'read:users': 'Read user profiles',
  'write:users': 'Create and update users',
  'delete:users': 'Delete users',
  'read:billing': 'View billing information',
  'write:billing': 'Modify billing'
};

// Scope validation middleware
function requireScope(...requiredScopes) {
  return (req, res, next) => {
    const grantedScopes = req.apiKey?.scopes || req.token?.scope?.split(' ') || [];
    const hasAll = requiredScopes.every(s => grantedScopes.includes(s));
    
    if (!hasAll) {
      return res.status(403).json({
        error: 'Insufficient scope',
        required: requiredScopes,
        granted: grantedScopes
      });
    }
    next();
  };
}

app.get('/api/admin/users', requireScope('read:users', 'admin'), getAllUsers);
app.delete('/api/users/:id', requireScope('delete:users'), deleteUser);

// WRONG — hardcoded
const stripe = new Stripe('sk_live_hardcoded_key_here');

// WRONG — in version control
// config.js: module.exports = { apiKey: 'sk_live_...' }

// CORRECT — environment variable
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);

// CORRECT — secrets manager (AWS Secrets Manager, HashiCorp Vault)
const { SecretsManagerClient, GetSecretValueCommand } = require('@aws-sdk/client-secrets-manager');
const secretsClient = new SecretsManagerClient({ region: 'us-east-1' });

async function getStripeKey() {
  const response = await secretsClient.send(
    new GetSecretValueCommand({ SecretId: 'prod/stripe/api-key' })
  );
  return JSON.parse(response.SecretString).stripe_secret_key;
}