API authentication (OAuth, JWT, API keys) in HLD - Architecture Diagram

System Overview - API authentication (OAuth, JWT, API keys)

This system secures API access using three common methods: OAuth for delegated access, JWT for stateless token validation, and API keys for simple client identification. It ensures only authorized users or applications can use the API, protecting resources and data.

Architecture Diagram

User
  |
  v
Load Balancer
  |
  v
API Gateway
  |
  +-------------------------+
  |                         |
  v                         v
Auth Service             Resource Service
  |                         |
  v                         v
Token Store (DB)         Data Store (DB)
  |
  v
Cache (for tokens)

Components

User

client

Initiates API requests with authentication credentials

Load Balancer

load_balancer

Distributes incoming API requests evenly to API Gateway instances

API Gateway

api_gateway

Central entry point that validates authentication and routes requests

Auth Service

service

Handles OAuth flows, issues JWT tokens, and validates API keys

Token Store (DB)

database

Stores OAuth tokens and API key metadata securely

Cache (for tokens)

cache

Caches token validation results for faster authentication checks

Resource Service

service

Processes authorized API requests and accesses protected data

Data Store (DB)

database

Stores the actual protected resources and application data

Request Flow - 14 Hops

User → Load Balancer

Load Balancer → API Gateway

API Gateway → Cache (for tokens)

Cache (for tokens) → API Gateway

API Gateway → Auth Service

Auth Service → Token Store (DB)

Token Store (DB) → Auth Service

Auth Service → Cache (for tokens)

Auth Service → API Gateway

API Gateway → Resource Service

Resource Service → Data Store (DB)

Resource Service → API Gateway

API Gateway → Load Balancer

Load Balancer → User

Failure Scenario

Component Fails:Token Store (DB)

Impact:Auth Service cannot validate tokens or API keys, causing authentication failures and blocking API access.

Mitigation:Use replicated databases for high availability and fallback to cache for recent token validations to allow read-only access temporarily.

Architecture Quiz - 3 Questions

Which component first checks if a token validation result is already available to speed up authentication?

A Auth Service

B API Gateway

C Cache (for tokens)

D Token Store (DB)

Design Principle

This architecture uses a layered approach to authentication, combining caching for speed, a dedicated Auth Service for security logic, and a central API Gateway for request control. It balances performance and security by validating tokens efficiently and isolating responsibilities.

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