Skip to content
Round RobinRound Robin

Scopes and access

A team API key has scopes and a rotation selector. Both restrict what the integration can access.

You need: a team API key for the workspace. Participant tokens use the separate participant workflow.

Choose scopes

Section titled “Choose scopes”
Scope Operations
read:oncall Rotation reads, schedules, on-call state, history, activity, cover and swap reads, and direct-assignment previews
write:duty Rotate, set on duty, and create, change or end direct assignments
write:rotation Create and update rotations and coverage, delete rotations, and manage rotation availability
manage:webhook Read and manage workspace webhook endpoints

Every key includes read:oncall. Give an integration only the write scopes its task requires.

write:duty on a team key does not authorize accepting cover or swaps for a person. Those actions require a member access token and participant permissions.

Choose rotations

Section titled “Choose rotations”
Selector Access
AllRotations Every rotation in the workspace, including later additions
Rotations The rotations selected when the key is created

Creating an all-rotations key requires workspace administration rights. For a selected-rotations key, the creator must administer the selected rotations.

A restricted key cannot create a rotation outside its selector. Webhook access is workspace-wide and cannot be narrowed by the rotation selector.

Check a refusal

Section titled “Check a refusal”

Call GET /v1/keys/self to inspect the key’s scopes and selector.

Result What to do
403 scope_denied Use a key with the scope required by this operation.
403 resource_denied Check the selected rotations and workspace.
Participant operation refuses an API key Use the authenticated member workflow; adding key scopes does not supply a participant identity.

Next steps

Section titled “Next steps”