Skip to content

Capability gateway

The gateway is the FastAPI edge over Polaris's services. It serves the Brain Builder web app (web/brain-builder/) and outside integrations from one app: CORS, REST, WebSocket chat and SSE. The web app's contract is web/brain-builder/src/lib/api/contract.ts.

Integrating from outside? These are the public, documented surfaces:

The rest of this page describes the routes the web app uses. They take only a signed-in session, not an API key, and may change without notice.

Auth (JWT and refresh tokens)

  • Login: POST /v1/auth/login {email,password} → {access_token, refresh_token, expires_in, token_type:"bearer", principal}.
  • Refresh: POST /v1/auth/refresh {refresh_token} → the same bundle with a NEW access and a NEW refresh token (rotating, single-use). An invalid, expired or reused refresh token is 401 invalid_refresh (reuse revokes the whole chain, to limit theft). Logout: POST /v1/auth/logout {refresh_token} → {ok:true}.
  • GET /v1/auth/me (Bearer) → principal. POST /v1/auth/accounts (platform admin) provisions accounts.
  • Refresh tokens are opaque and stored hashed (app.refresh_token). Access JWTs are short-lived (JWT_EXPIRE_SECONDS); the refresh TTL is REFRESH_EXPIRE_SECONDS (default 7 days).
  • REST: Authorization: Bearer <jwt>. WebSocket and SSE: ?token=<jwt> (browsers can't set those headers).
  • Two account types: tenant_user (bound to one brain_id and a role: Admin, Curator or Reader) and platform_admin (superuser: any brain, bypasses role checks, plus tenant management GET/POST /v1/brains).
  • API keys (sk-polaris-…) are for integrations. They work only on the public surfaces above, as far as their scopes allow. Presented to a web-app route, a key is 403 insufficient_scope.
  • Seed demo accounts: bb account seed (add more with bb account create):
email password type/role
admin@polaris.io polaris-admin-pw platform_admin
admin@meridian.legal meridian-admin-pw tenant Admin
curator@meridian.legal meridian-curator-pw tenant Curator
reader@meridian.legal meridian-reader-pw tenant Reader

Brain scoping

Every brain route has the brain in its path: /v1/brains/{brain_id}/…. The credential decides whether the caller may act on it:

  • A tenant user's token, or an API key, is bound to one brain. Any other brain_id in the path is 403 brain_forbidden.
  • The role comes from the credential (the account's role, or the key's). A role that can't run a route's verb is 403 role_forbidden.
  • A missing or invalid credential is 401.

There are no scoping headers: brain and role come only from the path and the credential.

Run

In development, ./scripts/dev.sh starts the stores, the gateway (uvicorn --reload on :8088) and the web app (:5174). See Dev loop. To run the gateway alone:

# the stores must be up and a brain certified (so serve has a published version)
./scripts/start-compose.sh
APP_CONFIG=$(pwd)/env/local/app.env PYTHONHASHSEED=0 \
  uv run uvicorn app.gateway.app:app --host 0.0.0.0 --port 8088

(uv run python -m app.gateway_service also works, on port 8000 with no reload.)

Web app surface (all under /v1)

  • REST: GET …/overview|corpus|sources|change-sets|change-sets/{id}|versions|lifecycle|manifests|audit|ops/{op_id}, POST …/sources|ingest/process|certify|rebuild, PATCH …/change-sets/{id} ({decision: approve|reject|edit}). Role-gated; 403 {error:{code:"role_forbidden"}} on a violation.
  • WebSocket chat: ws://host/v1/brains/{brain_id}/agents/{agent}/chat?token=<jwt>. Send {type:"query",verb,query,conversation_id}; receive routed → trace events (pre-gate → fsm → retrieve → assemble → reason → cite-then-verify → post-gate, from serve()'s on_stage hook) → envelope (+ artifact for assess/redline) → dashboard. Free text is routed to a verb; role-gated.
  • SSE: GET …/events?token=<jwt> (EventSource): source.ingest, change_set.created|updated, curation.approve|reject, lifecycle.certify, brain.published, op.progress, op.done, and more. Frames go on the default message channel (data: {SseEvent} with type in the body; the web app reads onmessage, not named events).
  • List shape: list endpoints return {items: [...], next_cursor}; single objects (overview, brain, lifecycle, change-set detail) are returned bare.

Wire the web app to the gateway

./scripts/dev.sh writes web/brain-builder/.env.development.local, which points the web app at the gateway on :8088. To do it by hand, set:

VITE_USE_MOCKS=false
VITE_API_BASE=http://localhost:8088/v1
VITE_WS_BASE=ws://localhost:8088/v1
VITE_SSE_BASE=http://localhost:8088/v1

Vite reads env only at startup, so restart the frontend after a change.

Notes

  • The event hub is in-process (one worker). A Redis-backed fan-out would extend it to several workers.
  • Long ops (certify, rebuild, ingest processing) run as background tasks, with progress on SSE and a pull fallback at GET …/ops/{op_id}.
  • serve() takes an optional on_stage callback (default None, no change in behaviour); the WebSocket passes it to stream the trace.