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

Practice

1. Which of the following is the primary purpose of API authentication?

easy

A. To verify the identity of the client accessing the API

B. To encrypt the data sent between client and server

C. To improve the speed of API responses

D. To log all API requests for analytics

Solution

1. Step 1: Understand the role of authentication

   Authentication is about confirming who is making the request, not about encryption or speed.

2. Step 2: Identify the correct purpose

   Verifying the client's identity ensures only authorized users access the API.

3. Final Answer:

   To verify the identity of the client accessing the API -> Option A

4. Quick Check:

   Authentication = Verify identity [OK]

Hint: Authentication means confirming who you are [OK]

Common Mistakes:

• Confusing authentication with encryption
• Thinking authentication speeds up API
• Mixing authentication with logging

2. Which of the following is the correct format of a JWT token?

easy

A. header.payload.signature

B. username:password

C. api_key=12345

D. token|timestamp|user

Solution

1. Step 1: Recall JWT structure

   A JWT token consists of three parts separated by dots: header, payload, and signature.

2. Step 2: Match the correct format

   Only the format with three dot-separated parts matches JWT.

3. Final Answer:

   header.payload.signature -> Option A

4. Quick Check:

   JWT = header.payload.signature [OK]

Hint: JWT always has three parts separated by dots [OK]

Common Mistakes:

• Confusing JWT with basic auth format
• Using equal signs instead of dots
• Mixing API key format with JWT

3. Given this OAuth flow: A client requests an access token using a refresh token. Which response indicates a successful token refresh?

medium

A. {"refresh_token": "xyz789"}

B. {"error": "invalid_grant"}

C. {"access_token": null}

D. {"access_token": "abc123", "expires_in": 3600}

Solution

1. Step 1: Understand OAuth token refresh response

   A successful refresh returns a new access token and expiry time.

2. Step 2: Identify the success response

   {"access_token": "abc123", "expires_in": 3600} contains a valid access token and expiry, indicating success.

3. Final Answer:

   {"access_token": "abc123", "expires_in": 3600} -> Option D

4. Quick Check:

   Success = new access token returned [OK]

Hint: Success returns new access token, not error or null [OK]

Common Mistakes:

• Confusing error response with success
• Expecting refresh token in response
• Assuming null access token means success

4. A developer uses an API key in the URL query string for authentication but notices security warnings. What is the main issue?

medium

A. API keys cannot be used for authentication

B. API keys must be encrypted with RSA

C. API keys in URLs can be logged or leaked easily

D. API keys expire too quickly

Solution

1. Step 1: Analyze API key usage in URLs

   URLs are often logged by servers, browsers, and proxies, risking key exposure.

2. Step 2: Identify the security risk

   Embedding API keys in URLs can leak them unintentionally, causing security warnings.

3. Final Answer:

   API keys in URLs can be logged or leaked easily -> Option C

4. Quick Check:

   API key in URL = risk of leakage [OK]

Hint: Never put API keys in URLs to avoid leaks [OK]

Common Mistakes:

• Thinking API keys must be encrypted always
• Believing API keys can't authenticate
• Assuming keys expire too fast

5. You design an API that uses JWT for authentication. To improve security, which combination is best practice?

hard

A. Store JWTs in localStorage and never expire them

B. Use short-lived JWTs with HTTPS and validate signature on each request

C. Send JWTs in URL query parameters for easy access

D. Use JWTs without signature to reduce overhead

Solution

1. Step 1: Identify secure JWT handling practices

   Short-lived tokens reduce risk if stolen; HTTPS protects data in transit; signature validation ensures token integrity.

2. Step 2: Evaluate options for security

   Use short-lived JWTs with HTTPS and validate signature on each request follows all best practices; others expose security risks like token theft or tampering.

3. Final Answer:

   Use short-lived JWTs with HTTPS and validate signature on each request -> Option B

4. Quick Check:

   Secure JWT = short life + HTTPS + signature check [OK]

Hint: Short life + HTTPS + signature check = secure JWT [OK]

Common Mistakes:

• Storing JWTs insecurely in localStorage
• Sending tokens in URLs risking leaks
• Skipping signature validation