Authentication
Authenticate with a personal token as a bearer token, the four scopes and what each allows, how tokens end, and the two token kinds that cannot be mixed.
The API authenticates with a personal token. Create one in Connect AI (see Tokens); it starts with sirmx_mcp_ and is shown once.
Send it#
Authorization: Bearer sirmx_mcp_…curl -s -H "Authorization: Bearer $TOKEN" "https://<your-breno-host>/api/v1/documents?limit=5"What a token is#
A token belongs to you, in one workspace. It sees exactly what you can see: the spaces you belong to, the sensitivity labels you are cleared for, and your own private items. It cannot do more than your role allows, and a viewer's token cannot write.
Scopes#
A token carries one or more scopes, chosen when it is created.
| Scope | Allows |
|---|---|
read | Listing and reading items, passage search, listing connectors and connected sources. |
ask | Answers with citations, including the streamed form. These spend coins. |
export | JSON and ZIP exports, and asynchronous export jobs and their download. |
write | Upload, link capture, and editing notes the token's owner created. |
A call outside the token's scopes returns 403 INSUFFICIENT_SCOPE, with the scope it needed in details.required_scope.
When a token stops working#
At once, when you revoke it, it expires, you leave the workspace, your account is erased, or the workspace is deleted. The next request returns 401 INVALID_TOKEN.
Two kinds of token#
| Kind | Where it works |
|---|---|
| Personal token | The REST API and the MCP server. |
| OAuth connector token (issued when Breno is added to Claude.ai or ChatGPT by URL) | MCP only. On the REST API it returns 401 TOKEN_AUDIENCE_MISMATCH. |
Everything else refuses tokens#
Deleting, sharing, members, settings, token management and connecting sources are not available to a token: they return 403 SESSION_REQUIRED. A leaked token can read, ask, export and write within its scopes, and nothing else, and cannot administer the workspace.
Audit#
Uploads, captures, note edits and exports made with a token are recorded in the workspace audit log with the token's id. See Audit log.