Reference: Scope catalog
The canonical v1 scope taxonomy served by GET /v1/scopes/catalog and consumed by the Role editor's picker. See Concepts: Scopes for the matching algorithm.
v1 catalog
users
Manage end-user identities.
| Scope | Effect |
|---|---|
users:read | List and view users. |
users:write | Create, update, soft-delete users; assign roles. |
users:impersonate | Send X-Acaso-User-Id with an unbound key. |
roles
Manage roles and their scope bundles.
| Scope | Effect |
|---|---|
roles:read | List and view roles. |
roles:write | Create, update, delete roles. |
agents
Run agents. This namespace uses a template scope.
| Scope | Effect |
|---|---|
agents:<name>:run | Run a specific agent. Substitute the concrete agent name. |
Example: agents:team-finder:run grants run-access to the team-finder agent only.
context
Read and write graphium context.
| Scope | Effect |
|---|---|
context:read | Read context visible to the caller. |
context:write | Ingest, patch, delete context. |
cultivators
Manage Cultivators — the autonomous reflectors that propose context into graphium memory.
| Scope | Effect |
|---|---|
cultivators:read | List Cultivator Kinds and their bindings; read run history and audit detail. |
cultivators:write | Create, update, and delete bindings — enable or disable a Kind, override its model and prompt, and narrow its scope and runtime grants. |
connections
Manage the tenant's MCP connections — the server registry investigator Cultivators reach through. An engineer/ops surface; the console has no Connections page today.
| Scope | Effect |
|---|---|
connections:read | List and view the tenant's MCP connections. |
connections:write | Register, update, and delete MCP connections — URL, auth secret reference, and tool allowlist. |
conversations
Read and write conversations on behalf of others.
| Scope | Effect |
|---|---|
conversations:read_others | Read chats belonging to other users in the tenant. |
conversations:write_others | Edit chat metadata for other users in the tenant. |
pii
PII operations.
| Scope | Effect |
|---|---|
pii:erase | Invoke right-to-erasure for a person. |
acaso_os
Platform administration.
| Scope | Effect |
|---|---|
acaso_os:admin | Full administrative access. Super-scope, satisfies every check. |
What admin gates today
Several endpoint families are gated solely by acaso_os:admin in v1: tenants, API keys, audit log, metrics, agent overrides, and health.
A future spec may split these into finer-grained scopes (tenants:write, audit:read, etc.). Such an addition is non-breaking because acaso_os:admin continues to match everything under the existing wildcard semantics.
Custom scopes
Tenant-specific scopes outside this catalog (team:engineering, project:atlas) are added via the Role editor's free-form chips input. They use the same matching algorithm and are validated as lowercase segment-wise strings. Bare * is rejected at write time.
Adding a scope
Adding a new namespace or scope to the catalog requires a code change in packages/datahub/src/datahub/scopes/catalog.py. Once shipped, the new entry appears in the catalog response and the Role editor picker without any console-side change.