Authorization
Roster checks authorization in two layers:
- A credential must have the required surface scope, such as
api:participants:writeormcp:resolve. - The credential owner must be allowed to act on the target project, participant, delegation, label, or resolve request.
Scopes never bypass platform access. An API key with a write scope can only
write data its owning identity is allowed to manage. Effective API-key access is
key scopes ∩ owner rights ∩ resource rules; the legacy all scope expands
only the scope dimension.
Platform Roles
Section titled “Platform Roles”| Role | Access model |
|---|---|
admin | Can manage platform configuration and project data globally. |
project_owner | Can create projects and manage projects where the identity is recorded as an owner. |
member | Can sign in and can read projects that allow authenticated users or list the identity as a project member. |
Project management is stored on project membership. An owner row grants
management. A member row grants read-only access to live projects.
Project status gates lifecycle visibility before read_access_mode: normal
readers can see only live projects, while admins and project owners can see
owned non-deleted projects in any status.
Entity CRUD
Section titled “Entity CRUD”| Entity | REST scopes | MCP scopes | Authorization rule |
|---|---|---|---|
| Projects | api:projects:read, api:projects:write | mcp:projects:read, mcp:projects:write | Reads follow project status and read access. Admins operate globally. Project owners can create projects and update or delete owned projects. |
| Participants | api:participants:read, api:participants:write | mcp:participants:read, mcp:participants:write | Reads follow project read access. Writes require ownership of the current project; moving a participant also requires ownership of the target project. |
| Participant members | api:participants:read, api:participants:write | mcp:participants:read, mcp:participants:write | Directory users and groups can be attached only to participants the actor can manage. |
| Directory records search | api:participants:read | mcp:participants:read | Cached directory records are exposed for participant association through the same participant-read gate. |
| Labels | api:labels:read, api:labels:write | mcp:labels:read, mcp:labels:write | Active authenticated users can read the global label catalog. Admins and effective project owners can create and update labels. Non-admin project owners can delete only labels they created, and only when every usage is in projects they own. |
| Delegations | api:delegations:read, api:delegations:write | mcp:delegations:read, mcp:delegations:write | Admins read and manage any delegation. Project owners read and manage participant-scoped delegations for owned participants when the delegator is represented on that participant. Users read and manage their own eligible delegation context. |
| Resolve history | api:resolve-requests:read | mcp:resolve-requests:read | Admins can read all history. Project owners can read history for owned projects. Active users can read their own requests. |
Write scopes include their matching read scopes when generated through Roster’s
scope presets. For example, selecting api:projects:write also adds
api:projects:read.
Resolve Authorization
Section titled “Resolve Authorization”Resolving asks Roster to answer “who should handle this?” against project, participant, directory, label, delegation, and metadata context.
| Surface | Required scope | Access rule |
|---|---|---|
| REST | api:resolve | The API-key owner can resolve only against visible project and participant context. |
| MCP | mcp:resolve | The MCP actor can resolve only against visible project and participant context. |
mode: "test" runs resolution without persisting a live workflow event.
mode: "live" records the resolve request for audit and observability when the
caller is authorized. Broad Resolve uses only readable live projects. A
project with status: "test" can be resolved only when project_id is
provided, mode: "test" is used, and the caller is an admin or project owner.
draft and archived projects are excluded from Resolve.
Resolve output can include delegated contacts when active delegations apply. Delegations are runtime overlays for resolver membership expansion; they do not mutate the synced directory entries.
Practical Patterns
Section titled “Practical Patterns”Use a narrow key for agents that only answer routing questions:
api:resolve api:resolve-requests:readmcp:resolve mcp:resolve-requests:readUse project and participant write scopes only for trusted automation that needs to create or maintain Roster data:
api:projects:write api:participants:write api:labels:write api:delegations:writemcp:projects:write mcp:participants:write mcp:labels:write mcp:delegations:writeEven with those scopes, the key owner still needs the correct platform role and project ownership.