api-api-authentication

Implementing API authentication for new services

API Authentication

Scope: Authentication strategies, JWT, OAuth 2.0, API keys, token management Lines: ~784 Last Updated: 2025-10-18

When to Use This Skill

Activate this skill when:

• Implementing API authentication for new services
• Choosing between authentication methods (JWT, OAuth, API keys)
• Securing REST or GraphQL APIs
• Implementing token refresh patterns
• Adding multi-factor authentication (MFA)
• Debugging authentication issues or token validation
• Migrating between authentication strategies

Core Concepts

Authentication vs Authorization

Authentication: Verifying identity ("Who are you?") Authorization: Verifying permissions ("What can you do?")

Example:

Authentication: User logs in with email/password → Gets token
Authorization: Token includes role "admin" → Can access admin endpoints

---

Authentication Method Comparison

Decision Matrix

| Method | Best For | Complexity | Mobile-Friendly | Stateless | Revocable | |--------|----------|------------|-----------------|-----------|-----------| | JWT | Microservices, mobile apps | Medium | Yes | Yes | No* | | OAuth 2.0 | Third-party integrations, delegated access | High | Yes | Yes | Yes | | API Keys | Server-to-server, simple APIs | Low | Limited | Yes | Yes | | Sessions | Traditional web apps | Low | No | No | Yes |

*JWT requires token blacklisting for revocation

When to Use Each Method

JWT (JSON Web Tokens):

• Microservices architecture (no shared session store)
• Mobile apps (persistent authentication)
• Single-page applications (SPAs)
• Stateless APIs

OAuth 2.0:

• Third-party application access ("Sign in with Google")
• Delegated authorization (access user's data without password)
• Multiple clients (web, mobile, desktop)
• Enterprise integrations

API Keys:

• Server-to-server communication
• Internal services
• Simple authentication needs
• Rate limiting by client

Sessions (Cookie-based):

• Traditional server-rendered web apps
• Need immediate revocation
• Single domain applications

---

JWT (JSON Web Tokens)

Structure

A JWT consists of three Base64-encoded parts separated by dots:

header.payload.signature

Example:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Header

Contains token type and signing algorithm:

{
  "alg": "HS256",  // Algorithm (HS256, RS256)
  "typ": "JWT"     // Token type
}

Algorithms:

• HS256 (HMAC SHA-256): Symmetric, shared secret
• RS256 (RSA SHA-256): Asymmetric, public/private key
• ES256 (ECDSA SHA-256): Asymmetric, elliptic curve

Payload (Claims)

Contains user data and metadata:

{
  "sub": "1234567890",        // Subject (user ID)
  "name": "John Doe",         // Custom claim
  "email": "john@example.com", // Custom claim
  "role": "admin",            // Custom claim
  "iat": 1516239022,          // Issued at (Unix timestamp)
  "exp": 1516242622,          // Expiration (Unix timestamp)
  "nbf": 1516239022,          // Not before
  "iss": "https://api.example.com", // Issuer
  "aud": "https://app.example.com"  // Audience
}

Standard claims:

• sub: Subject (user identifier)
• exp: Expiration time (required for security)
• iat: Issued at
• iss: Issuer (who created the token)
• aud: Audience (who the token is for)

Signature

Ensures token integrity:

// HS256 (symmetric)
HMACSHA256(
  base64UrlEncode(header) + "." + base64UrlEncode(payload),
  secret_key
)

// RS256 (asymmetric)
RSASHA256(
  base64UrlEncode(header) + "." + base64UrlEncode(payload),
  private_key
)

JWT Implementation Examples

Python (PyJWT)

import jwt
from datetime import datetime, timedelta

# Generate token
def create_token(user_id: int, role: str) -> str:
    payload = {
        "sub": str(user_id),
        "role": role,
        "iat": datetime.utcnow(),
        "exp": datetime.utcnow() + timedelta(hours=1)
    }
    return jwt.encode(payload, "your-secret-key", algorithm="HS256")

# Validate token
def validate_token(token: str) -> dict:
    try:
        payload = jwt.decode(
            token,
            "your-secret-key",
            algorithms=["HS256"],
            options={"verify_exp": True}
        )
        return payload
    except jwt.ExpiredSignatureError:
        raise Exception("Token has expired")
    except jwt.InvalidTokenError:
        raise Exception("Invalid token")

Node.js (jsonwebtoken)

import jwt from 'jsonwebtoken';

// Generate token
function createToken(userId: string, role: string): string {
  return jwt.sign(
    { sub: userId, role },
    process.env.JWT_SECRET,
    { expiresIn: '1h', algorithm: 'HS256' }
  );
}

// Validate token
function validateToken(token: string): any {
  try {
    return jwt.verify(token, process.env.JWT_SECRET, {
      algorithms: ['HS256']
    });
  } catch (error) {
    if (error.name === 'TokenExpiredError') {
      throw new Error('Token expired');
    }
    throw new Error('Invalid token');
  }
}

Go (golang-jwt)

import (
    "time"
    "github.com/golang-jwt/jwt/v5"
)

type Claims struct {
    UserID int    `json:"sub"`
    Role   string `json:"role"`
    jwt.RegisteredClaims
}

// Generate token
func CreateToken(userID int, role string) (string, error) {
    claims := &Claims{
        UserID: userID,
        Role:   role,
        RegisteredClaims: jwt.RegisteredClaims{
            ExpiresAt: jwt.NewNumericDate(time.Now().Add(1 * time.Hour)),
            IssuedAt:  jwt.NewNumericDate(time.Now()),
        },
    }

    token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
    return token.SignedString([]byte("your-secret-key"))
}

// Validate token
func ValidateToken(tokenString string) (*Claims, error) {
    claims := &Claims{}
    token, err := jwt.ParseWithClaims(tokenString, claims, func(token *jwt.Token) (interface{}, error) {
        return []byte("your-secret-key"), nil
    })

    if err != nil || !token.Valid {
        return nil, err
    }
    return claims, nil
}

JWT Best Practices

✅ Always set expiration (exp claim) - Short-lived tokens (15min-1hr) ✅ Use strong secret keys - At least 256 bits for HS256 ✅ Validate signature - Always verify before trusting payload ✅ Use RS256 for microservices - Public key validation, no shared secret ✅ Store minimal data - JWTs sent with every request (size matters)

❌ Don't store sensitive data - JWTs are readable (Base64 encoded, not encrypted) ❌ Don't use for session management alone - Hard to revoke ❌ Don't store in localStorage - Vulnerable to XSS attacks ❌ Don't make tokens long-lived - Compromised tokens can't be revoked

---

OAuth 2.0

OAuth 2.0 Flows

Authorization Code Flow (Most Secure)

Use case: Server-side web apps, mobile apps with PKCE

User                    Client App              Auth Server            Resource Server
  |                         |                        |                        |
  |--1. Click "Login"------>|                        |                        |
  |                         |--2. Redirect to------->|                        |
  |                         |   /authorize           |                        |
  |<------3. Login page---------------------------|                        |
  |                         |                        |                        |
  |--4. Enter credentials------------------------>|                        |
  |                         |                        |                        |
  |<--5. Redirect with authorization code---------|                        |
  |    (to callback URL)    |                        |                        |
  |                         |                        |                        |
  |--6. Code to client----->|                        |                        |
  |                         |--7. Exchange code----->|                        |
  |                         |    for tokens          |                        |
  |                         |<--8. Access token------|                        |
  |                         |    + Refresh token     |                        |
  |                         |                        |                        |
  |                         |--9. Request with access token----------------->|
  |                         |<--10. Protected resource-----------------------|

Implementation (Python with Authlib):

from authlib.integrations.flask_client import OAuth

oauth = OAuth(app)
oauth.register(
    'google',
    client_id='YOUR_CLIENT_ID',
    client_secret='YOUR_CLIENT_SECRET',
    server_metadata_url='https://accounts.google.com/.well-known/openid-configuration',
    client_kwargs={'scope': 'openid email profile'}
)

@app.route('/login')
def login():
    redirect_uri = url_for('callback', _external=True)
    return oauth.google.authorize_redirect(redirect_uri)

@app.route('/callback')
def callback():
    token = oauth.google.authorize_access_token()
    user_info = oauth.google.parse_id_token(token)
    # Store token and user_info in session
    return redirect('/dashboard')

Client Credentials Flow (Server-to-Server)

Use case: Service-to-service authentication (no user involved)

Service A                 Auth Server
    |                          |
    |--1. POST /token--------->|
    |   (client_id + secret)   |
    |                          |
    |<--2. Access token--------|
    |                          |
    |--3. API request--------->|
    |   with access token      |

Implementation:

import requests

# Get access token
response = requests.post('https://auth.example.com/oauth/token', data={
    'grant_type': 'client_credentials',
    'client_id': 'your_client_id',
    'client_secret': 'your_client_secret',
    'scope': 'read write'
})

token = response.json()['access_token']

# Use token to access API
api_response = requests.get(
    'https://api.example.com/resource',
    headers={'Authorization': f'Bearer {token}'}
)

Refresh Token Flow

Use case: Get new access token without re-authentication

Client                    Auth Server
  |                           |
  |--1. POST /token---------->|
  |   (refresh_token)         |
  |                           |
  |<--2. New access token-----|
  |   + New refresh token     |

Implementation:

async function refreshAccessToken(refreshToken: string): Promise<string> {
  const response = await fetch('https://auth.example.com/oauth/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      grant_type: 'refresh_token',
      refresh_token: refreshToken,
      client_id: process.env.CLIENT_ID,
      client_secret: process.env.CLIENT_SECRET
    })
  });

  const data = await response.json();
  return data.access_token;
}

OAuth 2.0 Best Practices

✅ Use PKCE (Proof Key for Code Exchange) for mobile/SPAs ✅ Validate redirect URIs - Prevent authorization code interception ✅ Short-lived access tokens (5-15 minutes) + long-lived refresh tokens ✅ Store refresh tokens securely - Encrypted database or secure storage ✅ Implement token rotation - Issue new refresh token on each use

---

API Keys

When to Use API Keys

Best for:

• Server-to-server communication
• Internal microservices
• Third-party integrations (customers accessing your API)
• Rate limiting and usage tracking

Not suitable for:

• User authentication (use JWT or sessions)
• Frontend apps (keys exposed to users)

API Key Implementation

import secrets
import hashlib
from datetime import datetime

# Generate API key
def generate_api_key() -> tuple[str, str]:
    # Generate random key
    key = secrets.token_urlsafe(32)  # 32 bytes = 256 bits

    # Hash for storage
    key_hash = hashlib.sha256(key.encode()).hexdigest()

    return key, key_hash  # Return both (show key once, store hash)

# Validate API key
def validate_api_key(provided_key: str) -> bool:
    provided_hash = hashlib.sha256(provided_key.encode()).hexdigest()

    # Look up in database
    stored_key = db.query("SELECT key_hash FROM api_keys WHERE key_hash = ?", [provided_hash])

    return stored_key is not None

API Key Storage

Database schema:

CREATE TABLE api_keys (
    id SERIAL PRIMARY KEY,
    key_hash VARCHAR(64) NOT NULL UNIQUE,  -- SHA-256 hash
    user_id INT NOT NULL,
    name VARCHAR(255),                      -- Key description
    scopes TEXT[],                          -- Permissions
    rate_limit_per_hour INT DEFAULT 1000,
    created_at TIMESTAMP DEFAULT NOW(),
    last_used_at TIMESTAMP,
    expires_at TIMESTAMP,
    revoked BOOLEAN DEFAULT FALSE
);

CREATE INDEX idx_api_keys_hash ON api_keys(key_hash);
CREATE INDEX idx_api_keys_user ON api_keys(user_id);

API Key Middleware (FastAPI)

from fastapi import Security, HTTPException, status
from fastapi.security import APIKeyHeader
import hashlib

api_key_header = APIKeyHeader(name="X-API-Key", auto_error=False)

async def validate_api_key(api_key: str = Security(api_key_header)):
    if not api_key:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="API key required"
        )

    key_hash = hashlib.sha256(api_key.encode()).hexdigest()

    # Check database
    key_data = await db.fetch_one(
        "SELECT * FROM api_keys WHERE key_hash = ? AND revoked = FALSE",
        [key_hash]
    )

    if not key_data:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Invalid API key"
        )

    # Check expiration
    if key_data['expires_at'] and key_data['expires_at'] < datetime.now():
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="API key expired"
        )

    # Update last_used_at
    await db.execute(
        "UPDATE api_keys SET last_used_at = NOW() WHERE id = ?",
        [key_data['id']]
    )

    return key_data

---

Token Storage and Transmission

Storage Options

| Storage | Pros | Cons | Best For | |---------|------|------|----------| | httpOnly Cookie | XSS-safe, automatic sending | CSRF risk (needs protection) | Web apps (same domain) | | localStorage | Persistent, easy access | XSS vulnerable | Not recommended | | sessionStorage | Tab-scoped, cleared on close | XSS vulnerable | Temporary data | | Memory (React state) | XSS-safe if no innerHTML | Lost on refresh | SPAs with refresh tokens | | Secure native storage | OS-level encryption | Platform-specific | Mobile apps |

Recommended: httpOnly Cookie (Web Apps)

from fastapi import Response

@app.post('/login')
async def login(response: Response, credentials: LoginRequest):
    # Validate credentials
    user = authenticate(credentials.email, credentials.password)

    # Generate token
    token = create_jwt(user.id, user.role)

    # Set httpOnly cookie
    response.set_cookie(
        key="access_token",
        value=token,
        httponly=True,      # Not accessible via JavaScript (XSS protection)
        secure=True,        # HTTPS only
        samesite="strict",  # CSRF protection
        max_age=3600        # 1 hour
    )

    return {"message": "Login successful"}

Transmission: Authorization Header

Bearer token (standard for JWTs and OAuth):

GET /api/user/profile HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

API key header:

GET /api/data HTTP/1.1
Host: api.example.com
X-API-Key: sk_live_abc123def456...

---

Token Refresh Patterns

Pattern 1: Automatic Refresh (Before Expiration)

let accessToken = '...';
let refreshToken = '...';
let tokenExpiry = Date.now() + 3600000; // 1 hour

// Interceptor to refresh token before requests
async function getValidToken(): Promise<string> {
  // Refresh 5 minutes before expiry
  if (Date.now() > tokenExpiry - 300000) {
    const response = await fetch('/auth/refresh', {
      method: 'POST',
      body: JSON.stringify({ refresh_token: refreshToken })
    });

    const data = await response.json();
    accessToken = data.access_token;
    tokenExpiry = Date.now() + data.expires_in * 1000;

    if (data.refresh_token) {
      refreshToken = data.refresh_token; // Token rotation
    }
  }

  return accessToken;
}

Pattern 2: Retry on 401 (After Expiration)

async function apiRequest(url: string, options: RequestInit = {}) {
  const response = await fetch(url, {
    ...options,
    headers: {
      ...options.headers,
      'Authorization': `Bearer ${accessToken}`
    }
  });

  // Token expired
  if (response.status === 401) {
    // Refresh token
    const newToken = await refreshAccessToken(refreshToken);
    accessToken = newToken;

    // Retry original request
    return fetch(url, {
      ...options,
      headers: {
        ...options.headers,
        'Authorization': `Bearer ${accessToken}`
      }
    });
  }

  return response;
}

---

Multi-Factor Authentication (MFA)

TOTP (Time-based One-Time Password)

Use case: Second factor for sensitive operations

import pyotp
import qrcode
from io import BytesIO

# Generate MFA secret for user
def setup_mfa(user_id: int) -> dict:
    secret = pyotp.random_base32()

    # Store secret in database (encrypted)
    db.execute(
        "UPDATE users SET mfa_secret = ? WHERE id = ?",
        [encrypt(secret), user_id]
    )

    # Generate QR code for authenticator app
    totp_uri = pyotp.totp.TOTP(secret).provisioning_uri(
        name=user.email,
        issuer_name="YourApp"
    )

    qr = qrcode.make(totp_uri)
    buffer = BytesIO()
    qr.save(buffer, format='PNG')

    return {
        "secret": secret,  # Show once to user
        "qr_code": buffer.getvalue()
    }

# Verify MFA code
def verify_mfa(user_id: int, code: str) -> bool:
    user = db.fetch_one("SELECT mfa_secret FROM users WHERE id = ?", [user_id])
    secret = decrypt(user['mfa_secret'])

    totp = pyotp.TOTP(secret)
    return totp.verify(code, valid_window=1)  # Allow 30s window

MFA Login Flow

1. User enters email/password
2. Validate credentials → Generate temporary token
3. Require MFA code (SMS, TOTP, email)
4. Validate MFA code
5. Issue full access token

---

Security Checklist

JWT Security

• [ ] Set short expiration (exp claim: 15min-1hr)
• [ ] Use strong secret key (256+ bits for HS256)
• [ ] Always validate signature before trusting payload
• [ ] Use RS256 for microservices (public key validation)
• [ ] Don't store sensitive data in payload
• [ ] Validate iss (issuer) and aud (audience) claims
• [ ] Implement token blacklist for logout (if needed)

OAuth 2.0 Security

• [ ] Use PKCE for mobile/SPAs
• [ ] Validate redirect URIs (exact match)
• [ ] Use state parameter (CSRF protection)
• [ ] Short-lived access tokens (5-15min)
• [ ] Secure refresh token storage (encrypted database)
• [ ] Implement refresh token rotation
• [ ] Use HTTPS only for token endpoints

API Key Security

• [ ] Generate cryptographically secure keys (256+ bits)
• [ ] Store hashed keys only (SHA-256 or better)
• [ ] Implement rate limiting per key
• [ ] Support key revocation
• [ ] Set expiration dates
• [ ] Log key usage for audit trail
• [ ] Use HTTPS only for key transmission
• [ ] Never expose keys in URLs (use headers)

General Security

• [ ] Use HTTPS everywhere
• [ ] Implement rate limiting
• [ ] Log authentication attempts (detect brute force)
• [ ] Use CORS appropriately
• [ ] Implement CSRF protection for cookies
• [ ] Validate all inputs
• [ ] Use secure password hashing (bcrypt, Argon2)
• [ ] Implement account lockout after failed attempts

---

Auth Method Decision Tree

Start: What are you building?
│
├─ Third-party access (users sign in with Google/GitHub)?
│  └─ Use OAuth 2.0 (Authorization Code Flow + PKCE)
│
├─ Server-to-server communication?
│  └─ Use API Keys (with rate limiting)
│
├─ Mobile app or SPA?
│  ├─ Need user identity from third party?
│  │  └─ OAuth 2.0 + JWT
│  └─ Custom authentication?
│     └─ JWT (access + refresh tokens)
│
├─ Microservices architecture?
│  └─ JWT with RS256 (public key validation)
│
├─ Traditional web app (server-rendered)?
│  └─ Sessions (httpOnly cookies) or JWT (cookies)
│
└─ Internal admin tool?
   └─ Sessions (simplest) or API Keys

---

Level 3 Resources

This skill includes comprehensive reference materials, executable scripts, and implementation examples.

Reference Materials

api-authentication/resources/REFERENCE.md (~300 lines):

• JWT specification (RFC 7519) - Complete technical reference
• OAuth 2.0 framework (RFC 6749) - Authorization flows and grant types
• PKCE extension (RFC 7636) - Proof Key for Code Exchange
• Token storage best practices - Browser, mobile, server-side
• Security considerations - Algorithm confusion, CSRF, XSS, token replay
• Attack vectors and mitigations - Comprehensive security guide
• Password hashing algorithms - Argon2, bcrypt, scrypt comparison
• Implementation checklist - JWT, OAuth, API key requirements

Executable Scripts

api-authentication/resources/scripts/:

1. test_jwt.py - JWT security testing and validation

• Validate JWT tokens with full security checks
• Generate tokens with proper claims
• Inspect token structure (header, payload, signature)
• Run attack tests (none algorithm, weak secrets, algorithm confusion)
• Check expiration, signature, and claim validation

1. test_oauth_flow.py - OAuth 2.0 flow validator

• Test authorization endpoints (Authorization Code Flow)
• Test token endpoints (Client Credentials, Refresh Token)
• Validate PKCE implementation
• Check state parameter and redirect URI validation
• Verify HTTPS enforcement

1. benchmark_hashing.py - Password hashing benchmark

• Compare bcrypt, Argon2id, and scrypt
• Auto-tune Argon2 parameters for target time (250-500ms)
• Statistical analysis (mean, median, stdev)
• Memory usage comparison

Usage Examples:

# JWT validation
python test_jwt.py --token "eyJhbGc..." --validate --secret "key" --algorithm HS256

# OAuth testing
python test_oauth_flow.py --auth-url https://auth.example.com/authorize \
                          --client-id ID --redirect-uri https://app.example.com/callback

# Hashing benchmark
python benchmark_hashing.py --compare --iterations 50

Implementation Examples

api-authentication/resources/examples/:

• python/jwt_authentication.py - Complete FastAPI JWT auth with Argon2
• typescript/jwt-auth-client.ts - React/TypeScript auth client with automatic refresh
• ci-cd/jwt-security-check.yml - GitHub Actions security validation

See api-authentication/resources/scripts/README.md for detailed documentation.

---

Related Skills

• network-resilience-patterns.md - Retry logic for auth failures
• modal-web-endpoints.md - Securing Modal endpoints with auth
• ios-networking.md - iOS auth patterns with URLSession
• database-selection.md - Storing user credentials and tokens

---

Last Updated: 2025-10-27 Format Version: 1.0 (Atomic) Resources: Level 3 (Reference, Scripts, Examples)