API authentication (OAuth, JWT, API keys) in HLD - System Design Exercise

Design: API Authentication System

Design covers authentication mechanisms and token/key management. Authorization policies and API business logic are out of scope.

Functional Requirements

FR1: Allow clients to securely authenticate to APIs

FR2: Support multiple authentication methods: OAuth 2.0, JWT tokens, and API keys

FR3: Ensure tokens and keys can be validated efficiently

FR4: Allow token expiration and revocation

FR5: Support scopes or permissions to restrict API access

FR6: Provide secure storage and management of API keys and secrets

Non-Functional Requirements

NFR1: Handle up to 100,000 authentication requests per minute

NFR2: API response latency for authentication should be under 100ms (p99)

NFR3: System availability target of 99.9% uptime

NFR4: Secure handling of sensitive credentials and tokens

NFR5: Scalable to support growing number of clients and APIs

Think Before You Design

Questions to Ask

❓ Question 1

❓ Question 2

❓ Question 3

❓ Question 4

❓ Question 5

❓ Question 6

Key Components

Authentication server or service

Token issuer and validator

API gateway or proxy for enforcing authentication

Secure storage for client credentials and keys

Revocation and expiration management

Logging and monitoring for authentication events

Design Patterns

OAuth 2.0 authorization code and client credentials flows

JWT token structure and validation

API key generation and validation

Token introspection and revocation lists

Caching token validation results for performance

Reference Architecture

Client
  |
  |--(1) Request token or API key --> Authentication Server
  |                                  (OAuth 2.0 / API key issuance)
  |
  |<--(2) Receive token or API key ---
  |
  |--(3) Call API with token/key --> API Gateway
  |                                  (Validate token/key)
  |
  |<--(4) API response -------------

Authentication Server --(5) Stores client credentials and keys securely

API Gateway --(6) Validates tokens (JWT signature or OAuth introspection)
             --(7) Checks scopes/permissions
             --(8) Forwards request to backend if valid

Revocation Service --(9) Maintains revoked tokens or keys list

Logging & Monitoring --(10) Tracks authentication events and failures

Components

Authentication Server

OAuth 2.0 server implementation (e.g., Keycloak, Auth0)

Issue OAuth tokens and API keys after validating client credentials

API Gateway

Nginx with Lua, Kong, or AWS API Gateway

Validate tokens or API keys on each API request and enforce access control

Token Validator

JWT library (e.g., jose, jsonwebtoken)

Verify JWT signature, expiration, and claims

Secure Credential Store

Encrypted database or vault (e.g., HashiCorp Vault, AWS Secrets Manager)

Store client secrets, API keys, and revocation data securely

Revocation Service

In-memory cache or database

Track revoked tokens or keys to deny access

Logging and Monitoring

ELK stack, Prometheus, Grafana

Audit authentication attempts and detect anomalies

Request Flow

1. Client sends credentials to Authentication Server to request OAuth token or API key.

2. Authentication Server validates client credentials and issues token or API key with scopes and expiration.

3. Client calls API Gateway with token or API key in request header.

4. API Gateway validates token signature or API key against stored credentials and revocation list.

5. If valid, API Gateway checks scopes/permissions and forwards request to backend API.

6. Backend API processes request and returns response through API Gateway to client.

7. Revocation Service updates revocation list when tokens or keys are revoked or expired.

8. Logging system records all authentication events for monitoring and auditing.

Database Schema

Entities: - Client: id (PK), name, secret_hash, allowed_scopes, created_at - APIKey: id (PK), client_id (FK), key_hash, scopes, created_at, expires_at, revoked (bool) - OAuthToken: token_id (PK), client_id (FK), user_id (optional), scopes, issued_at, expires_at, revoked (bool) - RevocationList: token_id or api_key_id, revoked_at Relationships: - Client has many APIKeys - Client has many OAuthTokens - RevocationList references tokens or keys to mark revoked status

Scaling Discussion

Bottlenecks

Authentication Server CPU and memory under high token issuance load

API Gateway latency due to token validation on every request

Database or vault performance for credential and revocation lookups

Revocation list size growing large affecting validation speed

Solutions

Use horizontal scaling and load balancing for Authentication Server

Cache token validation results at API Gateway with short TTL to reduce repeated validation

Use fast in-memory stores (Redis) for revocation lists and credential lookups

Implement token expiration to limit revocation list size and periodically clean revoked entries

Use stateless JWT tokens to reduce database lookups for validation

Interview Tips

Time: Spend 10 minutes understanding requirements and clarifying scope, 20 minutes designing components and data flow, 10 minutes discussing scaling and trade-offs, 5 minutes summarizing.

Explain differences and use cases for OAuth, JWT, and API keys

Describe how tokens are issued, validated, and revoked

Discuss security best practices for storing secrets and keys

Highlight caching and stateless token benefits for performance

Address scalability challenges and solutions clearly

Mention monitoring and auditing importance for security