Authorization

Roster checks authorization in two layers:

1. A credential must have the required surface scope, such as api:participants:write or mcp:resolve.
2. 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

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

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.
Team members	api:team-members:read, api:team-members:write	mcp:team-members:read, mcp:team-members:write	Admin-only. Manage human platform identities.
AI agents	api:ai-agents:read, api:ai-agents:write	mcp:ai-agents:read, mcp:ai-agents:write	Admin-only. Manage AI agent identities.
Service accounts	api:service-accounts:read, api:service-accounts:write	mcp:service-accounts:read, mcp:service-accounts:write	Admin-only. Manage service account identities.
API keys	api:api-keys:read, api:api-keys:write	mcp:api-keys:read, mcp:api-keys:write	Admin-only. List, inspect, create, and revoke API keys. API key token plaintext is returned only on create.
Audit events	api:audit-events:read	mcp:audit-events:read	Admin-only and license-gated. Read-only audit history.
Model runs	api:model-runs:read	mcp:model-runs:read	Admin-only and license-gated. Read-only model run traces.
Provider connectors	api:provider-connectors:read, api:provider-connectors:write	mcp:provider-connectors:read, mcp:provider-connectors:write	Admin-only. Manage identity provider connectors.
Platform settings	api:platform-settings:read, api:platform-settings:write	mcp:platform-settings:read, mcp:platform-settings:write	Admin-only. Read and update redacted platform settings.

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

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.

Resolve defaults to mode: "live" on API, MCP, CLI, and playground surfaces. 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 readable live projects in live mode and resolvable test projects in test mode. A project with status: "test" can be resolved when mode: "test" is used and the caller is an admin or project owner with access to that test project. 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

Use a narrow key for agents that only answer routing questions:

api:resolve api:resolve-requests:read
mcp:resolve mcp:resolve-requests:read

Use 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:write
mcp:projects:write mcp:participants:write mcp:labels:write mcp:delegations:write

Even with those scopes, the key owner still needs the correct platform role and project ownership.