Connection Scopes

What each scope permits, how they combine with your workspace role, and which set to pick.

What this does

Every API and MCP token carries an explicit list of scopes. A scope is resource:action — schedule:read, leaves:write — and the token can do exactly what its scopes allow and nothing else.

Two controls sit on top of the list:

• Read-only mode denies every :write scope at request time, regardless of what is stored on the token
• Your workspace role caps what you can grant in the first place

The scopes

Scope	Type	Permits
workspace:read	Read	Workspace name, timezone, active agent count, enabled feature modules
agents:read	Read	List agents with holiday group, off days and active status
agents:write	Write	Create and update agents
schedule:read	Read	Read the schedule grid, find coverage gaps, find available agents
schedule:write	Write	Assign and unassign agents to schedule slots
leaves:read	Read	Read leave requests and balances
leaves:write	Write	Create leave requests, approve and reject them
holidays:read	Read	Read public holidays and holiday groups
holidays:write	Write	Create and update holidays
ot:read	Read	Read overtime events, submissions and slot coverage
ot:write	Write	Create OT events, approve and reject submissions
reports:read	Read	Read work report submissions and missed-report tracking

Scope-to-tool mapping

Scope	MCP tools
workspace:read	get_workspace_info
agents:read	list_agents
schedule:read	get_schedule, find_coverage_gaps, find_available_agents
schedule:write	assign_shift, unassign_shift
leaves:read	list_leaves
leaves:write	create_leave, update_leave_status
holidays:read	list_holidays
ot:read	list_ot_events, get_ot_coverage
reports:read	get_missed_reports

How restrictions combine

Restrictions intersect. A token's real permissions are:

granted scopes  ∩  what your workspace role allows  ∩  (read-only ? reads only : everything)

Every layer can only narrow, never widen.

Role caps

Your role	Can grant
Owner	Everything in the catalogue
Admin	All reads and all writes
Lead	All reads, plus schedule:write and leaves:write
Member	Reads only: workspace:read, agents:read, schedule:read, leaves:read, holidays:read, ot:read

If you ask for a scope above your role, it is silently dropped from the token rather than erroring — so a client requesting a scope we later restrict does not break. If every requested scope is above your role, token creation fails with an explanation.

TIP

Role caps are re-checked when a token is edited, and against the token owner's role rather than the editor's. An admin tightening a member's token cannot widen it beyond what that member could have granted themselves.

Read-only mode

Read-only is evaluated on every request, not baked into the token at creation. Flipping an existing token to read-only stops writes on the very next call — no rotation, no reconfiguring your client.

On MCP connections, read-only additionally hides the write tools from tools/list, so the model never attempts one.

Choosing a scope

Intended use	Recommended scopes
Asking questions about coverage and leave	Read-only: workspace:read, agents:read, schedule:read, leaves:read, holidays:read
Daily standup / handover summaries	Read-only: the above plus reports:read, ot:read
Filling coverage gaps from chat	agents:read, schedule:read, schedule:write
Handling leave requests	agents:read, leaves:read, leaves:write, schedule:read
A dashboard or reporting integration	Read-only, every :read scope
Full agent assistance	Read and write, all scopes — owner or admin only

Start read-only. Most of the value here is in asking questions, and you can widen a token later without rotating it.

One token per client. A separate token for your laptop, your desktop and any integration means the activity log tells you which one did what, and losing a device means revoking one token rather than all of them.

Editing a live connection

From Settings → API & MCP you can change a token's scopes or its read-only flag at any time. The token string does not change, so pasted client configs keep working. Changes apply on the next call.

Revoking is permanent. The token row is kept so past entries in the activity log still have a name to attribute calls to, but the token stops working immediately.

The workspace kill switch

Workspace owners can disable API and MCP access for the entire workspace in one action. Every token stops working immediately and returns a 403 explaining why. Re-enabling restores them all — no tokens are lost.

Use it when you suspect a token has leaked and want to stop everything before working out which one.

Related

• MCP server setup — connecting a client
• MCP tool reference — every tool and its arguments
• REST API reference — the same permissions over plain HTTP