fastapi-commons
Reusable building blocks for FastAPI applications:
- Authentication: OIDC bearer tokens verified against the provider's JWKS (PyJWT), and database-backed API keys.
- Errors: exception classes that carry their HTTP status, app-level exception handlers, and a JSON 500 for anything unhandled.
- Request context: correlation IDs, client IP and log filters that put both into every log record.
- Metrics: a Prometheus middleware labelled by route template, and the
/metricsendpoint. - Tracing: OpenTelemetry setup, with the
otelextra.
Everything is a separate piece that the application wires itself. Importing the package has no side effects: no settings are read, no clients are created, and no logger is changed.
Requires Python 3.15.
Installation
uv add fastapi-commons # or: pip install fastapi-commons
uv add 'fastapi-commons[otel]' # with OpenTelemetry tracing
Wiring an application
from collections.abc import AsyncGenerator
from contextlib import asynccontextmanager
from typing import Annotated
from fastapi import Depends, FastAPI
from fastapi.middleware.cors import CORSMiddleware
from python3_commons.auth import TokenData
from python3_commons.conf import OIDCSettings
from fastapi_commons import (
CorrelationIDMiddleware,
LogContextMiddleware,
NotFoundError,
PrometheusMiddleware,
UnhandledErrorMiddleware,
get_token_verifier,
metrics,
oidc_lifespan,
register_exception_handlers,
)
@asynccontextmanager
async def lifespan(app: FastAPI) -> AsyncGenerator[None]:
async with oidc_lifespan(app, OIDCSettings()):
yield
app = FastAPI(lifespan=lifespan)
register_exception_handlers(app)
# add_middleware puts each new middleware outside the previous ones: the last one added runs first.
app.add_middleware(PrometheusMiddleware, app_name='orders')
app.add_middleware(UnhandledErrorMiddleware)
app.add_middleware(LogContextMiddleware)
app.add_middleware(CorrelationIDMiddleware)
app.add_middleware(CORSMiddleware, allow_origins=['https://app.example.com'], expose_headers=['X-Correlation-ID'])
app.add_route('/metrics', metrics, include_in_schema=False)
verify = get_token_verifier(TokenData)
class OrderNotFoundError(NotFoundError):
pass
@app.get('/orders/{order_id}')
async def get_order(order_id: int, token: Annotated[TokenData, Depends(verify)]) -> dict[str, int]:
raise OrderNotFoundError(f'order {order_id} does not exist')
The middleware order matters:
- CORS is outermost, so every response, including a 500, carries the CORS headers.
- CorrelationIDMiddleware sets the correlation ID before anything logs.
- LogContextMiddleware records the client IP for the log filters.
- UnhandledErrorMiddleware turns an unhandled exception into
{"detail": "Internal Server Error"}. Because it sits inside the first three, that 500 still has their headers. - PrometheusMiddleware is innermost, so it sees the exception, counts it and times the request including streamed bodies.
Authentication
OIDC bearer tokens
oidc_lifespan(app, settings) creates one OIDCClient (from python3-commons) for the application:
- it keeps the client on
app.statewhile the lifespan runs; - it closes the client on shutdown;
- it fails at startup when
OIDC_AUTHORITY_URLis missing.
get_token_verifier(token_cls) returns a FastAPI dependency that verifies the bearer token and returns its claims as token_cls, a TokenData subclass.
| Situation | Result |
|---|---|
| No credentials | 401 Not authenticated; with required=False the dependency returns None instead |
| Invalid, wrongly signed or wrong-audience token | 401 Token is invalid, WWW-Authenticate: Bearer error="invalid_token" |
| Expired token | 401 Token has expired |
| Provider or JWKS unreachable | 503 OIDC provider is not available |
oidc_lifespan not running |
500 |
How tokens are checked:
- Signing key: selected by the token's
kid. An unknownkidrefreshes the JWKS once, which handles key rotation. - Algorithms: only asymmetric ones are accepted,
algorithms=('RS256',)by default;HS*andnoneare refused when the verifier is created. - Audience: checked only when
OIDC_AUDIENCEis set. Thenaudis required and any configured value is accepted. With no audience configured,audis not checked. - Issuer: checked only when
OIDC_ISSUERis set. - Clock skew:
OIDC_LEEWAYseconds are allowed.
verify = get_token_verifier(TokenData) # -> TokenData
verify_optional = get_token_verifier(TokenData, required=False) # -> TokenData | None
# In tests, skip the provider altogether:
app.dependency_overrides[verify] = lambda: TokenData(exp=0, iat=0, iss='test', sub='alice')
The verifier reads the client from the application that serves the request (request.app.state), so a mounted sub-application must run its own oidc_lifespan.
API keys
get_api_key_verifier(session_dependency, header_name='X-API-Key') returns a dependency that looks the key up in python3-commons' api_keys table:
- a key that is not a UUID is rejected without a query;
- an expired key (
expires_atin the past) is rejected; session_dependencymay return theAsyncSessionor yield it.
The key is the row's primary key, so it is stored in plaintext.
Errors
Raise a ServiceError subclass and register_exception_handlers(app) answers with its status and {"detail": ...}:
| Class | Status |
|---|---|
BadRequestError |
400 |
UnauthorizedError |
401 |
ForbiddenError |
403 |
NotFoundError |
404 |
ConflictError |
409 |
UnavailableError |
503 |
ServiceError, or any other AppError |
500 |
How these are answered:
- A 4xx sends the exception's detail and is logged as one WARNING line.
- A 5xx sends only the status phrase and is logged at ERROR with the traceback.
headers=are passed through, for exampleUnauthorizedError('...', headers={'WWW-Authenticate': 'Bearer'}).- Errors raised in dependencies are handled too.
- Handlers the application registered itself for these types are left alone.
Built-in exceptions (ValueError, LookupError, ...) are not translated: an unexpected one is a 500, not a 400 or 404.
Request context and logging
CorrelationIDMiddleware:- An incoming
X-Correlation-IDis accepted when it matches[A-Za-z0-9._:-]{1,64}; otherwise a UUID is generated. - The ID is set on the response and is readable anywhere through
get_correlation_id(). fastapi_commons.contextholds the context variables. It imports nothing from FastAPI, so workers can use it too.
- An incoming
LogContextMiddleware: puts the client IP into the log context.get_client_ip(connection):- Returns the leftmost
X-Forwarded-Forentry when it is a valid IP address, otherwise the TCP peer. - The leftmost entry comes from the client. It can be trusted only when your edge proxy overwrites
X-Forwarded-Forand the application cannot be reached any other way. - The server may rewrite the peer itself. uvicorn's
--proxy-headers, on by default for connections from127.0.0.1, replaces the peer fromX-Forwarded-For, and the fallback then returns that address.
- Returns the leftmost
The log filters never fail outside a request: missing values render as -. Configure them in your own dictConfig:
LOGGING = {
'version': 1,
'filters': {
'correlation_id': {'()': 'fastapi_commons.log.filters.CorrelationIDFilter'},
'log_context': {'()': 'fastapi_commons.log.filters.LogContextFilter'},
'no_metrics': {'()': 'fastapi_commons.log.filters.EndpointFilter', 'paths': ['/metrics', '/health']},
},
'formatters': {
'default': {'format': '%(asctime)s %(levelname)s [%(correlation_id)s] [%(client_ip)s] %(name)s: %(message)s'},
},
'handlers': {
'console': {
'class': 'logging.StreamHandler',
'formatter': 'default',
'filters': ['correlation_id', 'log_context'],
},
},
'loggers': {
# The access logger of your server (uvicorn.access, granian.access, ...). The servers set propagate=False
# on it, so give it a handler here: an entry without one replaces the server's handler with nothing.
'granian.access': {'handlers': ['console'], 'filters': ['no_metrics'], 'propagate': False},
},
'root': {'level': 'INFO', 'handlers': ['console']},
}
Metrics
PrometheusMiddleware(app, app_name='fastapi-app', excluded_paths=...) records these metrics:
fastapi_requests_total,fastapi_responses_totalandfastapi_requests_duration_seconds;fastapi_exceptions_totalandfastapi_requests_in_progress;fastapi_app_info.
How the labels and timings are set:
- Labels: the route template (
/orders/{order_id}), including routers included with a prefix and mounted sub-applications. A request that matches no route gets the label<unmatched>, so the label count stays bounded. - Exclusions:
/metrics,/docs,/redocand/openapi.jsonare not recorded by default. - Timing: durations include streamed response bodies.
- Exemplars: a duration observation carries a
TraceIDexemplar when a sampled OpenTelemetry span is active.
The metrics live in the default registry and assume one worker per process.
Tracing (otel extra)
from fastapi_commons.instrumentation import setup_opentelemetry
setup_opentelemetry(app, service_name='orders')
What it does:
- Exporter: OTLP over gRPC, configured by the standard variables (
OTEL_EXPORTER_OTLP_ENDPOINT,OTEL_EXPORTER_OTLP_TRACES_ENDPOINT,OTEL_SERVICE_NAME,OTEL_RESOURCE_ATTRIBUTES). - Disabling:
OTEL_SDK_DISABLED=trueturns it off. - Repeat calls: it may be called more than once. The tracer provider is created once per process, or an SDK provider that is already installed is reused.
- Logging: with
log_correlation=True(the default) log records getotelTraceID,otelSpanIDandotelServiceName. Handlers and formats are left alone.
Configuration
The library reads no environment variables itself. OIDCSettings (python3-commons) reads these:
| Variable | Default | Meaning |
|---|---|---|
OIDC_AUTHORITY_URL |
- | Provider URL; required by oidc_lifespan |
OIDC_AUTHORITY_INTERNAL_HOST |
- | Internal host that replaces the authority's host for server-side calls |
OIDC_CLIENT_ID |
- | Not needed for token verification |
OIDC_CLIENT_SECRET |
- | Not needed for token verification |
OIDC_AUDIENCE |
- | Accepted audiences, comma-separated; empty: aud not checked |
OIDC_ISSUER |
- | Expected iss; empty: not checked |
OIDC_LEEWAY |
0 |
Allowed clock skew for exp and nbf, seconds |
OIDC_JWKS_CACHE_TTL |
300 |
Seconds the JWKS is cached |
OIDC_JWKS_REFRESH_INTERVAL |
60 |
Minimum seconds between JWKS refreshes for unknown key IDs |
OIDC_TIMEOUT |
10 |
Provider request timeout, seconds |
OIDC_VERIFY_CERT |
true |
Verify the provider's TLS certificate |
Tracing uses the standard OTEL_* variables.
Development
uv sync --all-extras
uv run ruff format src tests && uv run ruff check src tests
uv run ty check --error-on-warning src tests
uv run pyright src tests
uv run pytest --cov
pre-commit install runs the same checks before each commit.
Releasing
- Set
versioninpyproject.toml, and give the release its dated section inCHANGELOG.md(withMIGRATION.mdfor breaking changes). - Merge to
master. - Push a signed tag
vX.Y.Z.
The release workflow then:
- runs the checks;
- builds the distributions and checks that their version equals the tag;
- publishes to PyPI through Trusted Publishing;
- creates the GitHub release.
License
GPL-3.0-only. See LICENSE and AUTHORS.md.
Metadata
Release files for fastapi-commons 0.13.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| fastapi_commons-0.13.1.tar.gz | 54.7 kB | With provenance | Details for fastapi_commons-0.13.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| fastapi_commons-0.13.1-py3-none-any.whl | Python 3 | none | any | Details for fastapi_commons-0.13.1-py3-none-any.whl |
Total release size: 89.8 kB
Release files / fastapi_commons-0.13.1.tar.gz
| Download URL | fastapi_commons-0.13.1.tar.gz |
|---|---|
| Size | 54.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
23d14ba7f49fd05e1ca1d6dd19072699fc2457edfc8093d8277e6457abed41e4
|
|
BLAKE2b-256 checksum How to use checksums |
20d8bcfca824450c15496eb1a5579fd156aec7d21880eb5195a87b4c045420a3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.
Transparency logRelease files / fastapi_commons-0.13.1-py3-none-any.whl
| Download URL | fastapi_commons-0.13.1-py3-none-any.whl |
|---|---|
| Size | 35.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b6501324c9125cb85767b65980f0dd7b61275e0aef12ebc688d0dea291f8b4fb
|
|
BLAKE2b-256 checksum How to use checksums |
b54b4bb67f806d9e1479ab690a52c5f32cd775a09be0118126e4c968d216ca5d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.
Transparency logSecurity for fastapi-commons 0.13.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for fastapi_commons-0.13.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.