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:
- Questions Framework API: Questions, Answer Keys, evals, approvals and budget, with an OpenAPI schema.
- OpenAI-compatible Advisor:
POST /v1/brains/{brain_id}/chat/completions. - MCP endpoints: the Advisor at
/v1/mcpand the Questions Framework at/v1/mcp/questions.
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 is401 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 isREFRESH_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 onebrain_idand a role: Admin, Curator or Reader) andplatform_admin(superuser: any brain, bypasses role checks, plus tenant managementGET/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 is403 insufficient_scope. - Seed demo accounts:
bb account seed(add more withbb account create):
| 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_idin the path is403 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}; receiverouted→traceevents (pre-gate → fsm → retrieve → assemble → reason → cite-then-verify → post-gate, fromserve()'son_stagehook) →envelope(+artifactfor 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 defaultmessagechannel (data: {SseEvent}withtypein the body; the web app readsonmessage, 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 optionalon_stagecallback (defaultNone, no change in behaviour); the WebSocket passes it to stream the trace.