Skip to main content
Every protected operation requires a bearer token in the Authorization header:

​
Two accepted token types

The backend’s authentication seam is dual-accept: the single bearerAuth security scheme accepts either kind of token, and both resolve to the same pos.* scope vocabulary that the route guards enforce. Because both populate the same request context, one code path serves either principal — you do not pick a different endpoint or header depending on the token type.

​
The security scheme in the spec

The spec declares one HTTP bearer scheme (bearerAuth, bearerFormat: JWT). Every authenticated operation carries the bearer security requirement; only genuinely public routes (for example GET /health and the /v1 descriptor) omit it.

​
What you may do: whoami

To discover the scopes your token actually holds — before calling anything — request your effective permissions:
It returns your effective pos.* scopes, the same vocabulary the per-route guards enforce and the documented operations advertise as x-required-permissions:
whoami is one of the few routes with a { data: … } wrapper. The domain routes return their payload as raw JSON — see Making requests.

​
Scopes and authorization

A protected operation is gated on a pos.* scope. If your token is valid but lacks the required scope, the request is rejected with 403 FORBIDDEN; a missing or invalid token is 401 UNAUTHORIZED. See Error codes for the full map and Agent & MCP for how required permissions are advertised per operation.