Authentication
How a bearer API key resolves to a principal, its surfaces, and the audience the policy engine trusts.
Every request authenticates with a bearer API key. The key is not just a
credential — it is a principal. It resolves to a (tenant, product) and the
set of surfaces it is allowed to act on.
curl https://brain.example.com/v1/retrieve \
-H "Authorization: Bearer sa_live_..." \
-H "Content-Type: application/json" \
-d '{ "query": "...", "surface": "site_chatbot" }'Both header forms are accepted:
Prop
Type
Principals, surfaces, audience
A key carries one or more surfaces. A surface is a named context the key may
act in (e.g. site_chatbot, agent_assist), and each surface pins an
audience:
Prop
Type
The client never supplies scope
Audience, tenant, and allowed classifications are derived from the key — never
from the request body. A client cannot ask to see confidential data by
setting a flag; it can only present a key that the policy engine has already
bound to that clearance.
Surface selection
Requests name the surface they are acting under via the surface field. The key
must own that surface, or the request is rejected 401. Admin actions
(/v1/ingest, /v1/sources/website) additionally require the key to have an
internal_agent surface — the gateway picks it automatically.
On-behalf-of
An internal agent acting for a specific customer passes onBehalfOf: "<subjectId>".
This narrows the ACL tokens to that subject in addition to the agent's own
clearance — the audit trail records exactly whose data was in scope.
Errors
| Status | Meaning |
|---|---|
401 | Missing/invalid key, or the key does not own the requested surface. |
403 | Authenticated, but policy forbids the resolved scope (e.g. an admin action on a customer-only key). |
See Errors for the full envelope.