API Keys And Origins

Application identity is the front door to SPAPS. The middleware dependency layer extracts X-API-Key, validates it against the application table, records the application on request.state, and then applies tighter checks when the key is publishable and browser-facing.

Key Types

Type	Prefix	Intended caller	Main constraint
Publishable	`spaps_pub_`	Browser app	Endpoint allowlist and `Origin` validation
Secret	`spaps_sec_` or `spaps_`	Server process	Keep out of browsers and logs
Legacy	no required prefix	Migration path	Deprecated; production startup checks require disabling legacy auth

Origin Check Flow

Configure Browser Origins

Browser-facing traffic is configured on the application record. Update applications.allowed_origins for the app that owns the publishable key.


UPDATE applications
   SET allowed_origins = ARRAY['https://buildooor.com', 'http://localhost:3000']
 WHERE slug = 'buildooor';

Origin Validation Checklist

Check	Command or inspection	Expected signal	If it fails
Runtime is reachable	`curl -fsS http://localhost:3301/health`	Health response returns successfully	Start with Troubleshooting before editing app records
Local mode is intentional	`curl -fsS http://localhost:3301/health/local-mode`	Local-mode state matches the demo or deployment plan	Reconcile `DEVELOPMENT_ENVIRONMENT` and `SPAPS_LOCAL_MODE`
Browser origin is allowlisted	Inspect `applications.allowed_origins` for the app slug	The exact scheme, host, and port are present	Update the app record, not the frontend config only
Webhook and secret traffic use server keys	Review caller location and key prefix	Browser uses `spaps_pub_`; servers keep secret keys off the client	Rotate exposed secret keys and move calls server-side

Common Mistakes

Origin-only changes are database changes. They do not require a service restart, but they do require updating the correct application row.

Sending Authorization: Bearer <api key> with a JWT-shaped token. API-key extraction intentionally avoids treating JWTs as API keys.
Adding an origin to a frontend config file instead of the SPAPS application record.
Using a publishable key on an endpoint that requires a secret key.