API Authentication

REST endpoints currently require API-key bearer authentication.

curl "<your-roster-public-url>/api/v1/projects?limit=10" \
  -H "Authorization: Bearer ${ROSTER_API_KEY}"

const response = await fetch("<your-roster-public-url>/api/v1/projects?limit=10", {
  headers: {
    Authorization: `Bearer ${process.env.ROSTER_API_KEY}`,
  },
});

if (!response.ok) {
  throw new Error(`Roster API request failed: ${response.status}`);
}

const data = await response.json();

import os
import requests

response = requests.get(
    "<your-roster-public-url>/api/v1/projects?limit=10",
    headers={"Authorization": f"Bearer {os.environ['ROSTER_API_KEY']}"},
    timeout=10,
)
response.raise_for_status()
data = response.json()

API keys carry explicit api:* scopes. Endpoints also enforce platform authorization rules for the owning identity. Effective access is key scopes ∩ owner rights ∩ resource rules; scopes never elevate the key owner.

See Authorization for project ownership, entity CRUD, delegation, and resolve-access rules.

Authentication and authorization failures return strict Problem Details responses. Clients should branch on HTTP status and type, not on legacy error or message fields.

REST access also follows the current product license. Product limits and feature availability are reported through 403 /api/v1/problems/forbidden responses. GET /api/v1/status is available with api:status:read so clients can inspect access, license, limits, and features. The retained access object is a compatibility field and reports { "allowed": true, "code": "ok", "reason": null }.

Scopes

Scope	Purpose
`api:resolve`	Run resolve requests through REST.
`api:resolve-requests:read`	Read visible resolve request history.
`api:projects:read`	Read visible projects.
`api:projects:write`	Create, update, or delete manageable projects.
`api:participants:read`	Read visible participants and directory associations.
`api:participants:write`	Manage participants and participant members.
`api:labels:read`	Read the global label catalog as an active authenticated identity.
`api:labels:write`	Manage labels as an admin or effective project owner.
`api:delegations:read`	Read visible delegations.
`api:delegations:write`	Create, update, or revoke delegations.
`api:status:read`	Read sanitized deployment and license status.
`api:team-members:read`, `api:team-members:write`	Read or manage platform team members as an admin.
`api:ai-agents:read`, `api:ai-agents:write`	Read or manage AI agent identities as an admin.
`api:service-accounts:read`, `api:service-accounts:write`	Read or manage service account identities as an admin.
`api:api-keys:read`, `api:api-keys:write`	Read, create, or revoke API keys as an admin.
`api:audit-events:read`	Read audit events as an admin when the feature is available.
`api:model-runs:read`	Read model run traces as an admin when the feature is available.
`api:provider-connectors:read`, `api:provider-connectors:write`	Read or manage provider connectors as an admin.
`api:platform-settings:read`, `api:platform-settings:write`	Read or update platform settings as an admin.

Write scopes include their matching read scopes when generated through Roster’s scope presets. Scopes grant access to a surface, but the API-key owner still needs the matching platform role and project read or management access for the target entity.

Entity Authorization

Entity	Required scopes	Platform rule
Projects	`api:projects:read`, `api:projects:write`	Reads follow project status and read access. Admins operate globally. Project owners manage owned projects.
Participants and members	`api:participants:read`, `api:participants:write`	Participant reads follow project read access. Writes require project management access.
Directory records search	`api:participants:read`	Cached directory record lookup is exposed through participant access.
Labels	`api:labels:read`, `api: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`	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`	Admins read all history; project owners read history for owned projects; active users read their own requests.
Admin operations	Team-member, managed-identity, API-key, provider-connector, and platform-settings REST scopes.	The API-key owner must be an active platform admin. Scopes do not grant admin rights.
Audit events and model runs	`api:audit-events:read`, `api:model-runs:read`	Admin-only, read-only, and gated by the current edition’s feature availability reported by `GET /api/v1/status`.

Resolve Authorization

POST /api/v1/resolve requires api:resolve. Resolution only uses project and participant context visible to the API-key owner. Live resolve requests are recorded with the authenticated actor so request history can apply the same visibility rules later.

Planned Auth Modes

ROSTER_REST_AUTH_MODE is reserved for later REST auth-mode switching. Current REST implementation requires API-key bearer auth.