Architecture

Auth is a stateless Python 3.13 FastAPI service that validates JWTs for partners and Bubble.

System context

Partner/Bubble ---> Auth (FastAPI) ---> JWKS endpoint (issuer)
                       |-> Secret Manager (API key, Sentry DSN)
                       |-> Sentry (errors + traces)

Request flow

1. Client sends a request with X-API-Key.
2. APIKeyMiddleware validates the key.
3. /api/v1/jwt/verify validates token structure and issuer.
4. JWKS is fetched (or served from cache) and used to verify the token.
5. Response returns validation result and claims.

Components

• services/auth/main.py: app setup, middleware, Sentry lifecycle.
• services/auth/routers/: API routing.
• services/auth/api/v1/endpoints/jwt_verify.py: verification endpoint.
• services/auth/util/jwt_verify.py: JWKS fetch + JWT verification logic.
• services/auth/middleware/api_key_middleware.py: API key enforcement.
• packages/python/common/: Secret Manager utilities.

Reliability and scaling

• JWKS is cached in-memory for 300 seconds.
• JWKS fetches use httpx with a 5-second timeout.
• The service is stateless and scales horizontally.