API key authentication in FastAPI - Step-by-Step Execution

Concept Flow - API key authentication

Client sends request with API key

↓

Server receives request

↓

Extract API key from headers

↓

Check if API key is valid?

No→Reject request with 401

Yes↓

Allow access to protected resource

↓

Send response back to client

The server checks the API key sent by the client in the request headers. If valid, it allows access; otherwise, it rejects the request.

Execution Sample

FastAPI

from fastapi import FastAPI, Header, HTTPException
app = FastAPI()

@app.get("/items/")
async def read_items(x_api_key: str = Header(...)):
    if x_api_key != "secret123":
        raise HTTPException(status_code=401, detail="Invalid API Key")
    return {"message": "Access granted"}

This FastAPI code checks the API key from the request header and returns access granted if the key matches.

Execution Table

Step	Action	API Key Received	Check Result	Response
1	Client sends request with header x-api-key: 'secret123'	secret123	Matches expected key	Returns {"message": "Access granted"}
2	Client sends request with header x-api-key: 'wrongkey'	wrongkey	Does not match	Raises HTTP 401 Unauthorized error
3	Client sends request without x-api-key header	None	Missing key	Raises HTTP 422 Unprocessable Entity error

💡 Execution stops after sending response or raising error based on API key validation.

Variable Tracker

Variable	Start	After Step 1	After Step 2	After Step 3
x_api_key	N/A	secret123	wrongkey	None
Check Result	N/A	True	False	False

Key Moments - 2 Insights

Why does the request without the API key header cause an error?

Because the API key is required as a header parameter (Header(...)) and FastAPI automatically returns a 422 error if it is missing, as shown in execution_table step 3.

What happens if the API key does not match the expected value?

The code raises an HTTPException with status 401 Unauthorized, rejecting the request as shown in execution_table step 2.

Visual Quiz - 3 Questions

Look at the execution table, what response is returned when the API key is 'secret123'?

A Raises HTTP 401 Unauthorized error

B Returns {"message": "Access granted"}

C Raises HTTP 422 Unprocessable Entity error

D Returns an empty response

💡 Hint

Check execution_table row 1 under Response column.

At which step does the API key check fail due to a missing header?

A Step 1

B Step 2

C Step 3

D None of the above

💡 Hint

Look at execution_table row 3 where API Key Received is None.

If the expected API key changes to 'newkey', how would the check result change for step 1?

A Check Result becomes False

B Check Result remains True

C API key becomes None

D Response becomes HTTP 422 error

💡 Hint

Refer to variable_tracker for Check Result values and compare with new expected key.

Concept Snapshot

API key authentication in FastAPI:
- Client sends API key in request header (e.g., x-api-key)
- Server extracts key using Header dependency
- Server compares key to expected value
- If match, access granted; else HTTP 401 error
- Missing key causes HTTP 422 error automatically

Full Transcript

API key authentication in FastAPI works by requiring the client to send a secret key in the request header. The server uses FastAPI's Header dependency to extract this key. If the key matches the expected secret, the server allows access and returns a success message. If the key is wrong, the server raises a 401 Unauthorized error. If the key is missing, FastAPI automatically returns a 422 error because the header is required. This process ensures only clients with the correct API key can access protected resources.

Practice

1. What is the main purpose of using API key authentication in a FastAPI application?

easy

A. To restrict access to the API by requiring a secret key in requests

B. To speed up the API response time

C. To automatically generate API documentation

D. To format the API response as JSON

Solution

1. Step 1: Understand API key authentication purpose

   API key authentication is used to protect APIs by requiring a secret key from clients.

2. Step 2: Identify the correct purpose in options

   Only To restrict access to the API by requiring a secret key in requests describes restricting access using a secret key, which matches the purpose.

3. Final Answer:

   To restrict access to the API by requiring a secret key in requests -> Option A

4. Quick Check:

   API key authentication = restrict access [OK]

Hint: API keys control who can use the API [OK]

Common Mistakes:

• Confusing API key with speeding up API
• Thinking API key generates docs
• Assuming API key changes response format

2. Which FastAPI import is used to extract an API key from the request header?

easy

A. from fastapi import Header

B. from fastapi.security import APIKeyHeader

C. from fastapi.security import OAuth2PasswordBearer

D. from fastapi import Depends

Solution

1. Step 1: Identify the correct security class for API key in header

   FastAPI provides APIKeyHeader to extract API keys from headers.

2. Step 2: Compare options to find the exact import

   from fastapi.security import APIKeyHeader imports APIKeyHeader from fastapi.security, which is correct.

3. Final Answer:

   from fastapi.security import APIKeyHeader -> Option B

4. Quick Check:

   API key header extractor = APIKeyHeader [OK]

Hint: API keys in headers use APIKeyHeader import [OK]

Common Mistakes:

• Using OAuth2PasswordBearer for API keys
• Confusing Header with APIKeyHeader
• Missing import from fastapi.security

3. Given this FastAPI code snippet, what will be the response if the client sends a request without the 'X-API-Key' header?

from fastapi import FastAPI, Security, HTTPException
from fastapi.security import APIKeyHeader

app = FastAPI()
api_key_header = APIKeyHeader(name='X-API-Key')

@app.get('/secure')
async def secure_endpoint(api_key: str = Security(api_key_header)):
    if api_key != 'secret123':
        raise HTTPException(status_code=403, detail='Invalid API Key')
    return {'message': 'Access granted'}

medium

A. 403 Forbidden with detail 'Invalid API Key'

B. 200 OK with message 'Access granted'

C. 500 Internal Server Error

D. 422 Unprocessable Entity error

Solution

1. Step 1: Understand Security dependency behavior

   If the required header 'X-API-Key' is missing, FastAPI returns a 422 error before entering the function.

2. Step 2: Analyze the code's error handling

   The 403 error triggers only if the key is present but incorrect. Missing header causes 422 instead.

3. Final Answer:

   422 Unprocessable Entity error -> Option D

4. Quick Check:

   Missing header = 422 error [OK]

Hint: Missing required header causes 422 error [OK]

Common Mistakes:

• Assuming missing key triggers 403 error
• Expecting 200 OK without key
• Thinking server crashes with 500 error

4. Identify the error in this FastAPI API key authentication code:

from fastapi import FastAPI, Security, HTTPException
from fastapi.security import APIKeyHeader

app = FastAPI()
api_key_header = APIKeyHeader(name='X-API-Key')

@app.get('/data')
async def get_data(api_key: str = api_key_header):
    if api_key != 'topsecret':
        raise HTTPException(status_code=401, detail='Unauthorized')
    return {'data': 'Here is your data'}

medium

A. Missing Security() wrapper around api_key_header in function parameter

B. Incorrect HTTP status code for unauthorized access

C. APIKeyHeader should be named 'Authorization' instead of 'X-API-Key'

D. Function should be synchronous, not async

Solution

1. Step 1: Check how APIKeyHeader is used in dependency

   FastAPI requires Security() to wrap APIKeyHeader for dependency injection.

2. Step 2: Identify missing Security() in parameter

   The code uses api_key: str = api_key_header instead of Security(api_key_header).

3. Final Answer:

   Missing Security() wrapper around api_key_header in function parameter -> Option A

4. Quick Check:

   APIKeyHeader needs Security() [OK]

Hint: Wrap APIKeyHeader with Security() in parameters [OK]

Common Mistakes:

• Omitting Security() causes injection failure
• Using wrong header name is not an error here
• HTTP status 401 is acceptable for unauthorized

5. You want to secure multiple endpoints in FastAPI using the same API key header. Which approach is best to avoid repeating code?

hard

A. Use a global variable to store the API key and check it manually in each endpoint

B. Copy the API key check code inside every endpoint function

C. Create a reusable dependency function that checks the API key and use Security() with it

D. Disable authentication and rely on client honesty

Solution

1. Step 1: Understand code reuse in FastAPI dependencies

   FastAPI encourages reusable dependencies to share logic like API key checks.

2. Step 2: Identify best practice for API key checks

   Creating a dependency function with Security() allows clean reuse across endpoints.

3. Final Answer:

   Create a reusable dependency function that checks the API key and use Security() with it -> Option C

4. Quick Check:

   Reusable dependency = clean, DRY code [OK]

Hint: Use reusable dependency functions for API key checks [OK]

Common Mistakes:

• Copy-pasting code leads to duplication
• Using global variables breaks encapsulation
• Disabling authentication is insecure