Tenancy, roles and permissions
Tenant isolation
Every record belongs to one tenant, and isolation is enforced by the database, not only by application code. Row-level security is forced on every tenant table, and the application connects as a role that is bound by it.
- The tenant always comes from your token (or, for machine tokens, from the token's binding). It is never read from a request body or query string.
- A request for another tenant's record returns
404, as if it did not exist. - Machine tokens (
bst_,obt_) are bound to one tenant, and ingest tokens to one telemetry source.
Roles
| Role | In short |
|---|---|
admin | Everything, including keys, tokens, users and settings |
reviewer | Decides intake and approvals, authors policies |
auditor | Reads the Audit ledger and exports evidence |
viewer | Read-only. People who sign in with Microsoft for the first time start as viewers. |
Call GET /api/auth/me to see your role and the exact permission list that role grants. The server enforces permissions on every call; the list is there so you can build your own UI. A missing permission returns 403 with a detail such as Requires permission: view_security.
Permissions you will meet
| Permission | Gates |
|---|---|
view_ledger | Reading and verifying the Audit ledger |
export_audit | Ledger CSV export |
create_policies, manage_policies | Authoring and changing policies |
decide_approvals | Deciding approvals |
suspend_agents | Suspend and block |
view_security | The Security area: events, findings, incidents, shadow agents, assets |
investigate_security | Changing finding status, running triage, opening incidents |
manage_detections | Tuning detections and shadow signatures |
manage_observability | Ingest tokens, dead letters, retention and data policy |
export_evidence | Exporting security evidence (also needs the tenant data policy to allow it) |
view_sensitive_telemetry | Seeing unmasked identities and fields. Without it you see [restricted]. |
view_cost, manage_pricing | Cost figures and the price catalogue |
manage_assessments, accept_risk, resolve_critical | Vulnerability assessment actions |
view_integrations, manage_integrations | Connectors such as Salesforce |
Some read endpoints rely on tenant isolation alone and require no particular role. Do not assume a route is restricted because it appears in an admin section; check the response of GET /api/auth/me and the operation's description.
Who decides for an agent
For the Agent catalog, authority follows the agent: its owner can decide access requests; an admin can act as an override; a reviewer can act only when the agent has no active owner. Nobody can decide their own request.