Request Headers, Cookies and the Request Object

HTTP requests carry more than just a URL and body — headers provide metadata about the request (Content-Type, Authorization, User-Agent, Accept-Language) and cookies carry session state. FastAPI provides the Header and Cookie parameter functions to declare these as typed, validated function arguments just like path and query parameters. For cases where you need access to the full request — including raw headers, client IP, URL, method, or streaming body — FastAPI exposes the Starlette Request object as an injectable dependency.

Request Headers #

from fastapi import FastAPI, Header
from typing import Annotated

app = FastAPI()

# ── Declare a header parameter ────────────────────────────────────────────────
# FastAPI automatically converts header names:
# HTTP header "X-User-Id"  → function param "x_user_id" (hyphens to underscores)
# HTTP header "User-Agent" → function param "user_agent"

@app.get("/posts")
def list_posts(
    user_agent:  Annotated[str | None, Header()] = None,
    accept_lang: Annotated[str | None, Header(alias="accept-language")] = None,
):
    return {"user_agent": user_agent, "language": accept_lang}

# ── Custom application headers ─────────────────────────────────────────────────
@app.get("/internal/stats")
def get_stats(
    x_api_key:  Annotated[str, Header(description="Internal API key")],
    x_client_id: Annotated[str | None, Header()] = None,
):
    if x_api_key != "secret-internal-key":
        from fastapi import HTTPException
        raise HTTPException(403, "Invalid API key")
    return {"client": x_client_id, "stats": {}}

Request Cookies #

from fastapi import FastAPI, Cookie
from typing import Annotated

app = FastAPI()

@app.get("/profile")
def get_profile(
    session_id: Annotated[str | None, Cookie()] = None,
    theme:      Annotated[str, Cookie()] = "light",
):
    if session_id is None:
        from fastapi import HTTPException
        raise HTTPException(401, "Not authenticated")
    return {"session": session_id, "theme": theme}

# Cookie names map directly — no hyphen-to-underscore conversion
# Cookie: session_id=abc123; theme=dark

The Request Object #

from fastapi import FastAPI, Request
import json

app = FastAPI()

@app.get("/debug")
async def debug_request(request: Request):
    return {
        "method":       request.method,
        "url":          str(request.url),
        "path":         request.url.path,
        "query_string": str(request.query_params),
        "client_ip":    request.client.host if request.client else None,
        "headers":      dict(request.headers),
        "cookies":      dict(request.cookies),
    }

# ── Read raw request body ────────────────────────────────────────────────────
@app.post("/webhooks/raw")
async def receive_webhook(request: Request):
    # Read raw bytes — useful for HMAC signature verification
    body = await request.body()

    # Verify signature (e.g. GitHub webhook)
    import hmac, hashlib
    signature = request.headers.get("X-Hub-Signature-256", "")
    secret    = b"your_webhook_secret"
    expected  = "sha256=" + hmac.new(secret, body, hashlib.sha256).hexdigest()

    if not hmac.compare_digest(signature, expected):
        from fastapi import HTTPException
        raise HTTPException(401, "Invalid webhook signature")

    payload = json.loads(body)
    return {"received": True, "event": request.headers.get("X-GitHub-Event")}

Common Mistakes #

Mistake 1 — Header name with wrong underscore/hyphen convention #

❌ Wrong — expecting HTTP hyphen in Python parameter name:

def handler(x-api-key: str = Header()):   # SyntaxError — hyphens invalid in Python names

✅ Correct — FastAPI converts automatically:

def handler(x_api_key: Annotated[str, Header()]):   # ✓ x_api_key ↔ X-Api-Key header

Mistake 2 — Reading raw body after Pydantic body model (body already consumed) #

❌ Wrong — both a Pydantic body and raw body read:

async def handler(data: MyModel, request: Request):
    body = await request.body()   # empty! Pydantic already consumed it

✅ Correct — use only one body reading method. For HMAC verification, read raw body and parse JSON yourself.

Mistake 3 — Not handling missing optional headers #

❌ Wrong — required header causes 422 if not sent:

def handler(x_request_id: Annotated[str, Header()]):   # required! 422 if missing

✅ Correct — make it optional with a default:

def handler(x_request_id: Annotated[str | None, Header()] = None):   # ✓ optional

Quick Reference #