Bearer token handling in FastAPI - Step-by-Step Execution

Concept Flow - Bearer token handling

Client sends request with Authorization header

↓

Server reads Authorization header

↓

Check if header starts with 'Bearer '

↓

Extract token

↓

Validate token

↓

If valid: allow access

↓

If invalid: reject request

The server checks the Authorization header for a Bearer token, extracts it, validates it, and then allows or denies access.

Execution Sample

FastAPI

from fastapi import FastAPI, Depends, HTTPException, status
from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials

app = FastAPI()
security = HTTPBearer()

@app.get("/secure")
async def secure_route(credentials: HTTPAuthorizationCredentials = Depends(security)):
    token = credentials.credentials
    if token != "validtoken":
        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid token")
    return {"message": "Access granted"}

This FastAPI code checks for a Bearer token, validates it, and returns access granted or unauthorized.

Execution Table

Step	Action	Authorization Header	Token Extracted	Token Valid?	Result
1	Client sends request	Bearer validtoken			Request received
2	Server reads header	Bearer validtoken			Header read
3	Check header starts with 'Bearer '	Bearer validtoken		Yes	Proceed
4	Extract token	Bearer validtoken	validtoken		Token extracted
5	Validate token	Bearer validtoken	validtoken	Yes	Access granted
6	Return response				{"message": "Access granted"}
7	Client sends request	Bearer invalidtoken			Request received
8	Server reads header	Bearer invalidtoken			Header read
9	Check header starts with 'Bearer '	Bearer invalidtoken		Yes	Proceed
10	Extract token	Bearer invalidtoken	invalidtoken		Token extracted
11	Validate token	Bearer invalidtoken	invalidtoken	No	Raise 401 Unauthorized
12	Return response				HTTP 401 Unauthorized

💡 Execution stops after returning response based on token validity.

Variable Tracker

Variable	Start	After Step 4	After Step 5	After Step 10	After Step 11
Authorization Header		Bearer validtoken	Bearer validtoken	Bearer invalidtoken	Bearer invalidtoken
Token Extracted		validtoken	validtoken	invalidtoken	invalidtoken
Token Valid?			Yes		No
Result			Access granted		401 Unauthorized

Key Moments - 3 Insights

Why do we check if the header starts with 'Bearer ' before extracting the token?

Because the Authorization header might contain other schemes like 'Basic'. Checking ensures we only process Bearer tokens, as shown in steps 3 and 9 of the execution_table.

What happens if the token is invalid?

The server raises an HTTP 401 Unauthorized error and stops processing, as seen in steps 11 and 12 in the execution_table.

Why do we extract the token from the header instead of using the whole header value?

The header includes the word 'Bearer' plus the token. We only need the token part to validate it, as shown in steps 4 and 10 where the token is extracted.

Visual Quiz - 3 Questions

Look at the execution_table, what is the token extracted at step 10?

A validtoken

B invalidtoken

C Bearer invalidtoken

D No token extracted

💡 Hint

Check the 'Token Extracted' column at step 10 in the execution_table.

At which step does the server decide the token is invalid?

A Step 5

B Step 9

C Step 11

D Step 12

💡 Hint

Look at the 'Token Valid?' and 'Result' columns in the execution_table for when 'No' appears.

If the Authorization header was 'Basic abc123', what would happen?

A Token extracted and validated

B Request rejected because header does not start with 'Bearer '

C Access granted automatically

D Server crashes

💡 Hint

Refer to the decision at step 3 and 9 about checking the header prefix.

Concept Snapshot

Bearer token handling in FastAPI:
- Client sends Authorization header: 'Bearer <token>'
- Server checks header starts with 'Bearer '
- Extract token part after 'Bearer '
- Validate token (e.g., compare to expected value)
- If valid, allow access; if not, raise 401 Unauthorized
- Use HTTPBearer and HTTPAuthorizationCredentials for easy handling

Full Transcript

In Bearer token handling with FastAPI, the client sends a request with an Authorization header containing the token prefixed by 'Bearer '. The server reads this header and first checks if it starts with 'Bearer '. If it does, the server extracts the token part after 'Bearer ' and validates it. If the token matches the expected value, the server grants access and returns a success message. If the token is invalid or the header does not start with 'Bearer ', the server rejects the request with a 401 Unauthorized error. This process ensures secure access control using tokens. The FastAPI HTTPBearer security class helps manage this flow easily by extracting and validating tokens automatically.

Practice

1. What is the main purpose of using a Bearer token in FastAPI?

easy

A. To serve static files efficiently

B. To format JSON responses automatically

C. To speed up database queries

D. To securely identify and authorize API requests

Solution

1. Step 1: Understand Bearer token role

   Bearer tokens are used to prove the client has permission to access protected routes.

2. Step 2: Identify purpose in FastAPI

   FastAPI uses Bearer tokens to check authorization before allowing access to API endpoints.

3. Final Answer:

   To securely identify and authorize API requests -> Option D

4. Quick Check:

   Bearer token = Authorization [OK]

Hint: Bearer tokens are for security and access control [OK]

Common Mistakes:

• Confusing token with response formatting
• Thinking token speeds up database
• Assuming token serves static files

2. Which FastAPI class is used to extract a Bearer token from the Authorization header?

easy

A. OAuth2PasswordBearer

B. HTTPBasicCredentials

C. OAuth2PasswordRequestForm

D. APIKeyHeader

Solution

1. Step 1: Recall FastAPI token extraction classes

   OAuth2PasswordBearer is designed to read Bearer tokens from the Authorization header.

2. Step 2: Match class to Bearer token usage

   OAuth2PasswordRequestForm is for form data, HTTPBasicCredentials is for basic auth, APIKeyHeader is for API keys, so only OAuth2PasswordBearer fits Bearer tokens.

3. Final Answer:

   OAuth2PasswordBearer -> Option A

4. Quick Check:

   Bearer token extractor = OAuth2PasswordBearer [OK]

Hint: Bearer token uses OAuth2PasswordBearer class [OK]

Common Mistakes:

• Using OAuth2PasswordRequestForm for token extraction
• Confusing basic auth with Bearer token
• Choosing APIKeyHeader for Bearer tokens

3. Given this FastAPI dependency:

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")

@app.get("/users/me")
async def read_users_me(token: str = Depends(oauth2_scheme)):
    return {"token": token}

What will be the output if the client sends a request with header Authorization: Bearer abc123?

medium

A. {"token": "Bearer abc123"}

B. HTTP 401 Unauthorized error

C. {"token": "abc123"}

D. {"token": null}

Solution

1. Step 1: Understand OAuth2PasswordBearer behavior

   This class extracts only the token string after 'Bearer ' from the Authorization header.

2. Step 2: Analyze the returned value

   The function returns a JSON with the token string, so it will return {"token": "abc123"}.

3. Final Answer:

   {"token": "abc123"} -> Option C

4. Quick Check:

   Bearer token string extracted = "abc123" [OK]

Hint: OAuth2PasswordBearer strips 'Bearer ' prefix automatically [OK]

Common Mistakes:

• Expecting full 'Bearer abc123' string returned
• Assuming 401 error without token validation
• Thinking token is null if present

4. What is wrong with this FastAPI code snippet for Bearer token validation?

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")

@app.get("/items/")
async def read_items(token: str = Depends(oauth2_scheme)):
    if token == None:
        raise HTTPException(status_code=401, detail="Invalid token")
    return {"token": token}

medium

A. The token check should use 'if not token' instead of 'if token == None'

B. OAuth2PasswordBearer does not extract tokens from headers

C. The route path should not end with a slash

D. HTTPException requires a status_code of 403 for invalid tokens

Solution

1. Step 1: Check token validation logic

   OAuth2PasswordBearer returns a string or raises an error if missing; token is never None but can be empty or missing.

2. Step 2: Correct token presence check

   Using 'if not token' is safer to catch empty strings or missing tokens rather than 'token == None'.

3. Final Answer:

   The token check should use 'if not token' instead of 'if token == None' -> Option A

4. Quick Check:

   Token presence check = 'if not token' [OK]

Hint: Check token presence with 'if not token' for safety [OK]

Common Mistakes:

• Using 'token == None' which misses empty strings
• Thinking OAuth2PasswordBearer doesn't extract tokens
• Confusing HTTP status codes for auth errors

5. You want to protect a FastAPI route so only requests with the exact Bearer token "secret123" are allowed. Which code snippet correctly implements this?

hard

A. async def protected_route(token: str = Depends(oauth2_scheme)):
if token == None:
return {"message": "Access granted"}
raise HTTPException(status_code=401, detail="Unauthorized")

B. async def protected_route(token: str = Depends(oauth2_scheme)):
if token != "secret123":
raise HTTPException(status_code=401, detail="Unauthorized")
return {"message": "Access granted"}

C. async def protected_route(token: str):
if token == "secret123":
return {"message": "Access granted"}
raise HTTPException(status_code=403, detail="Forbidden")

D. async def protected_route(token: str = Depends(oauth2_scheme)):
if token == "Bearer secret123":
return {"message": "Access granted"}
raise HTTPException(status_code=401, detail="Unauthorized")

Solution

1. Step 1: Use OAuth2PasswordBearer dependency

   We must use Depends(oauth2_scheme) to extract the token from the Authorization header.

2. Step 2: Check token value correctly

   The token string is just the token without 'Bearer ' prefix, so compare directly to "secret123" and raise 401 if not matching.

3. Final Answer:

   async def protected_route(token: str = Depends(oauth2_scheme)): if token != "secret123": raise HTTPException(status_code=401, detail="Unauthorized") return {"message": "Access granted"} -> Option B

4. Quick Check:

   Compare token string directly to "secret123" [OK]

Hint: Compare token string directly, no 'Bearer ' prefix included [OK]

Common Mistakes:

• Comparing token to 'Bearer secret123' including prefix
• Not using Depends(oauth2_scheme) to get token
• Returning access granted when token is None