API Authentication

REST endpoints currently require API-key bearer authentication.

Curl

curl "https://roster.example.com/api/v1/projects?limit=10" \
  -H "Authorization: Bearer ${ROSTER_API_KEY}"

TypeScript

const response = await fetch("https://roster.example.com/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();

Python

import os
import requests

response = requests.get(
    "https://roster.example.com/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.

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.

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.

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.