Request Lifecycle

Every SPAPS request passes through shared HTTP concerns before it reaches a domain service. The important thing to understand is that application identity and user identity are separate checks: API key validation identifies the calling application, while JWT or local-mode identity identifies the user principal.

Sequence

The Key Dependencies

Dependency	File	Role
`get_db_session`	`middleware/spaps_deps.py`	Yields an async SQLAlchemy session from `app.state.db_resources`
`get_application`	`middleware/spaps_deps.py`	Extracts and validates `X-API-Key`, sets application state, enforces publishable-key route scope and origin rules
`get_current_user`	`middleware/spaps_deps.py`	Authenticates JWTs and enforces token application matching
`get_optional_user`	`middleware/spaps_deps.py`	Allows routes to handle anonymous or authenticated callers
`require_admin_user`	`middleware/spaps_deps.py`	Requires an authenticated admin principal

Local Mode Branch

In local mode, missing API keys fall back to a synthetic local application and test personas. Explicit API keys still resolve real applications, which keeps app-scoped entitlements and origin behavior testable in development.


DEVELOPMENT_ENVIRONMENT=local
SPAPS_LOCAL_MODE=true
curl 'http://localhost:3301/api/some-route?_user=admin'

Local mode is a development convenience. Startup checks refuse unsafe local-mode or production-credential combinations in production-like environments.

Failure Shape

Domain errors are routed through installed error handlers and JSON responses are wrapped by ResponseEnvelopeMiddleware. When debugging a status code, check dependency failures before service logic: missing API key, publishable-key scope, origin mismatch, JWT mismatch, and role checks all happen before the route’s business body matters.

Auth and local mode explains the identity branches.
API keys and origins focuses on application identity.
Troubleshooting maps common symptoms to layers.