Authentication Patterns for API Gateways

A practical guide to API authentication approaches, from simple API keys to JWT tokens and OAuth 2.0 flows. Includes decision trees, security considerations, and configuration examples.

Authentication Decision Tree

Is the API public (open data)?
├── Yes → No auth needed (but still rate limit!)
└── No → Who are the consumers?
    ├── Server-to-server (backend services)
    │   ├── Internal (same organization) → Mutual TLS or API Keys
    │   └── External (partners) → OAuth 2.0 Client Credentials
    ├── Browser/SPA apps → OAuth 2.0 + PKCE (no client secret!)
    ├── Mobile apps → OAuth 2.0 + PKCE
    └── Mixed (all of the above) → OAuth 2.0 with multiple grant types

Method Comparison

Pattern 1: API Key Authentication

The simplest form of authentication. The client includes a secret key in every request.

How It Works

Client → Gateway: GET /api/users
                   X-Api-Key: sk-abc123def456

Gateway: Look up "sk-abc123def456" in key store
         → Found: "Acme Corp Mobile App"
         → Forward request with X-Client-Name: acme-mobile

Gateway → Upstream: GET /api/users
                    X-Client-Name: acme-mobile
                    X-Request-Id: uuid-here

Security Considerations

• Transport: ALWAYS use HTTPS. API keys in plaintext over HTTP are trivially intercepted.
• Storage: Hash keys in your database (like passwords). Store the unhashed version only in the client.
• Rotation: Implement key rotation. Issue new key → client updates → revoke old key.
• Scoping: Don't use one key for everything. Separate keys per environment, per service, per access level.
• Headers > Query params: Keys in query strings end up in access logs, browser history, and referrer headers.

Anti-Patterns

BAD:  GET /api/users?api_key=sk-abc123    ← Key in URL (logged everywhere)
BAD:  Authorization: sk-abc123            ← No "Bearer" prefix (ambiguous)
GOOD: X-Api-Key: sk-abc123               ← Dedicated header
GOOD: Authorization: Bearer sk-abc123     ← Standard header with scheme

Pattern 2: JWT Authentication

JSON Web Tokens carry claims (user ID, roles, permissions) in a cryptographically signed payload. The gateway can verify the token without contacting an auth server.

How It Works

1. Client → Auth Server: POST /auth/login {email, password}
2. Auth Server → Client: {token: "eyJ...", refresh_token: "eyK..."}
3. Client → Gateway: GET /api/users
                     Authorization: Bearer eyJ...

4. Gateway: Decode JWT header → check algorithm
            Verify signature (HMAC or RSA)
            Check exp (not expired?)
            Check iss (correct issuer?)
            Extract claims (sub, role, tenant_id)

5. Gateway → Upstream: GET /api/users
                       X-User-Id: user-123
                       X-User-Role: admin
                       X-Tenant-Id: acme-corp

JWT Structure

Header:    {"alg": "RS256", "typ": "JWT", "kid": "key-2024-01"}
Payload:   {"iss": "auth.example.com", "sub": "user-123",
            "role": "admin", "exp": 1700003600, "iat": 1700000000}
Signature: RSASHA256(base64url(header) + "." + base64url(payload), private_key)

Algorithm Choice

HS256 (HMAC-SHA256):
  + Simple (shared secret)
  + Fast verification
  - Secret must be shared between auth server and gateway
  - If secret leaks, anyone can forge tokens
  - Hard to rotate (all services must update simultaneously)
  → Use for: Internal services you fully control

RS256 (RSA-SHA256):
  + Public key can be distributed freely (JWKS endpoint)
  + Only auth server needs the private key
  + Easy to rotate (publish new public key, keep old for grace period)
  - Slower verification (RSA math vs. HMAC)
  → Use for: Production APIs, external consumers, microservices

ES256 (ECDSA-SHA256):
  + Smaller keys and signatures than RSA
  + Same security model as RS256
  - Less library support in some languages
  → Use for: Mobile/IoT where bandwidth matters

Security Considerations

• Short-lived tokens: Access tokens should expire in 5-15 minutes. Use refresh tokens for longer sessions.
• Never store in localStorage: Vulnerable to XSS. Use httpOnly cookies or in-memory storage.
• Validate everything: Always check exp, iss, aud claims. Don't trust the alg header blindly.
• Revocation strategy: JWTs are stateless, so you can't "revoke" them. Options:
• Short expiry + refresh tokens (most common)
• Token blacklist (defeats statelessness but sometimes necessary)
• Token versioning in user record (check token_version claim against DB)

Pattern 3: OAuth 2.0 Flows

OAuth 2.0 is not an authentication protocol -- it's an authorization framework. Use OpenID Connect (OIDC) on top of OAuth 2.0 for authentication.

Flow Selection

Server-to-server (no user involved):
  → Client Credentials Grant
  → Client authenticates with client_id + client_secret
  → Gets an access token directly

Browser SPA (public client):
  → Authorization Code Grant + PKCE
  → User redirected to auth server login page
  → Auth server returns authorization code
  → Client exchanges code for tokens (with PKCE verifier)

Mobile app (public client):
  → Authorization Code Grant + PKCE (same as SPA)
  → Use deep links for redirect URI

Traditional web app (confidential client):
  → Authorization Code Grant (with client_secret)
  → Server-side code exchange (secret never exposed to browser)

Gateway Auth Configuration Quick Reference

Kong

# API Key auth
plugins:
  - name: key-auth
    config:
      key_names: [X-Api-Key, apikey]
      hide_credentials: true

# JWT auth
plugins:
  - name: jwt
    config:
      header_names: [Authorization]
      claims_to_verify: [exp]

AWS API Gateway

# Lambda authorizer (custom auth logic)
securitySchemes:
  lambda_authorizer:
    type: apiKey
    name: Authorization
    in: header
    x-amazon-apigateway-authorizer:
      type: token
      authorizerUri: "arn:aws:..."

Custom Gateway

See src/auth_middleware.py for API key authentication implementation.

Best Practices Checklist

• [ ] Use HTTPS for all API traffic (terminate TLS at the gateway or load balancer)
• [ ] Store secrets encrypted at rest (use a secret manager, not environment variables)
• [ ] Implement key/token rotation with overlapping validity periods
• [ ] Log authentication events (successes and failures) for audit trails
• [ ] Rate limit authentication endpoints more aggressively (prevent brute force)
• [ ] Return generic error messages (don't reveal whether a username exists)
• [ ] Use constant-time comparison for secrets (prevent timing attacks)
• [ ] Implement account lockout after N failed attempts
• [ ] Set appropriate token expiry (5-15 min access, 7-30 day refresh)
• [ ] Validate all JWT claims (exp, iss, aud, nbf)

Part of API Developer Pro. Support: support@datanest.dev

API Gateway Comparison: Kong vs. AWS API Gateway vs. Custom

A practical comparison to help you choose the right gateway for your architecture. Covers features, pricing, operational complexity, and migration strategies.

Quick Decision Matrix

Detailed Comparison

Feature Matrix

When to Choose Kong

Choose Kong when you need:

• Multi-cloud or hybrid-cloud deployment
• Running on Kubernetes (Kong Ingress Controller)
• Rich plugin ecosystem without vendor lock-in
• Control over the gateway infrastructure
• Custom plugin development in Lua, Go, or Python

Avoid Kong when:

• You want fully managed (no infra to maintain)
• Your team has no Kubernetes/container experience
• You need something running in < 1 hour

When to Choose AWS API Gateway

Choose AWS API Gateway when you need:

• Serverless architecture (Lambda backends)
• Quick setup with minimal infrastructure
• Deep AWS integration (IAM, Cognito, CloudWatch, WAF)
• Pay-per-use pricing (low-traffic APIs)

Avoid AWS API Gateway when:

• You're multi-cloud or might migrate later
• You need > 10K requests/second (need to request limit increase)
• You need complex request/response transformations
• You want to avoid VTL (Velocity Template Language) -- it's painful

When to Build Custom

Build custom when you need:

• Very specific gateway logic that no platform supports
• Learning/teaching how gateways work internally
• Lightweight internal tool routing (dev environments)
• Protocol-specific handling (custom binary protocols)

Avoid custom when:

• You need production-grade reliability at scale
• You don't have time to build AND maintain it
• Standard features (rate limiting, auth) are your main needs

Cost Comparison (Monthly Estimates)

Scenario: 10M API requests/month

Scenario: 1B API requests/month

Migration Guide

Kong to AWS API Gateway

1. Export Kong routes as OpenAPI spec

2. Add x-amazon-apigateway-* extensions

3. Replace Kong plugins with equivalent AWS features

4. Replace upstream health checks with ALB health checks

5. Update DNS to point to API Gateway endpoint

AWS API Gateway to Kong

1. Export API as OpenAPI spec (API GW console → Export)

2. Strip x-amazon-apigateway-* extensions

3. Convert to Kong declarative config (deck convert)

4. Map Lambda authorizers to Kong JWT/key-auth plugins

5. Set up upstream targets and health checks

6. Update DNS

Either to Custom

1. Document all routes, auth rules, and rate limits

2. Implement the core proxy with middleware pipeline

3. Port each plugin/feature one at a time

4. Load test to ensure comparable throughput

5. Shadow traffic (send to both old and new) for validation

6. Cut over DNS

Architecture Patterns

Pattern 1: Gateway per Service (Kong/Envoy)

Internet → Kong Gateway → Service A
                        → Service B
                        → Service C

Best for: Monolithic gateway, centralized policy.

Pattern 2: Gateway per Domain (AWS)

Internet → API GW (Users) → Lambda/ECS
         → API GW (Orders) → Lambda/ECS
         → API GW (Analytics) → Lambda/ECS

Best for: Team autonomy, independent scaling.

Pattern 3: Multi-Layer (Enterprise)

Internet → Edge Gateway (Kong/CloudFront)
             → Internal Gateway (Envoy/Custom)
                → Service Mesh (Istio/Linkerd)
                   → Services

Best for: Large organizations with different security zones.

What's In This Product

Each implementation demonstrates the same core features (routing, rate limiting, auth, transforms) so you can compare approaches directly.

Part of API Developer Pro. Support: support@datanest.dev