Appearance
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. Scopes only narrow what a token may touch; they never grant anything. What a scope actually lets you do depends on your role, which is checked live on every call. Agents are only offered the scopes their role can use (see Scopes agents are offered).
Two more controls sit on top of the list:
- Read-only mode denies every
:writescope at request time, regardless of what is stored on the token - Your workspace role decides what a scope can do for you (see What each write scope lets each role do)
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, update, deactivate and delete agents (staff; not agents linked to someone ranked at or above you) |
team:read | Read | List team members, their roles, linked agents and what you may do to each (staff) |
team:write | Write | Add team members, change roles, link agents and remove members ranked below you (staff) |
schedule:read | Read | Read the schedule grid, find coverage gaps, find available agents |
schedule:write | Write | Assign and unassign agents to schedule slots, and edit agents' weekly schedule templates |
leaves:read | Read | Read leave requests and balances (members: their own leave) |
leaves:write | Write | File, edit, approve, reject and delete leave and set balances (staff); request and cancel your own leave (members) |
holidays:read | Read | Read public holidays, holiday groups and built-in presets |
holidays:write | Write | Add, change and delete holidays and holiday groups, and import presets (staff) |
ot:read | Read | Read overtime events and your own OT availability. Managers, leads and the owner also read every event, submission and the slot coverage; members see only events they have been given access to |
ot:write | Write | Run OT events, grant access and review submissions (managers, leads, owner), or submit your own availability (members with a linked agent) |
reports:read | Read | Read work report templates, submissions, missed reports and the leaderboard (members: their own submissions and misses) |
reports:write | Write | Manage report templates and missed-report reminders (staff); silence missed reports and switch the banner (owner, lead); submit your own work reports and dismiss your notices (members with a linked agent) |
tickets:read | Read | Read support tickets and their replies (staff) |
tickets:write | Write | Open support tickets and reply to them (staff) |
notes:read | Read | Read your own dashboard notepad |
notes:write | Write | Replace your own dashboard notepad |
workspace:write | Write | Turn workspace modules on or off (staff; plan rules apply) |
Scope-to-tool mapping
| Scope | MCP tools |
|---|---|
| none (always available) | whoami |
workspace:read | get_workspace_info, list_modules |
agents:read | list_agents |
agents:write | create_agent, update_agent, set_agent_active, delete_agent |
team:read | list_team |
team:write | add_team_member, change_member_role, link_member_agent, remove_team_member |
schedule:read | get_schedule, find_coverage_gaps, find_available_agents, get_schedule_template |
schedule:write | assign_shift, unassign_shift, set_schedule_template |
leaves:read | list_leaves, get_leave_balances, get_my_leave |
leaves:write | create_leave, update_leave_status, update_leave, delete_leave, set_leave_balance, request_leave, cancel_leave_request |
holidays:read | list_holidays, list_holiday_groups, list_holiday_presets |
holidays:write | create_holiday, update_holiday, delete_holiday, create_holiday_group, update_holiday_group, delete_holiday_group, import_holiday_presets |
ot:read | list_ot_events, get_ot_event, get_ot_coverage, list_ot_submissions, get_ot_submission, list_my_ot_events, get_my_ot_availability |
ot:write | create_ot_event, update_ot_event, delete_ot_event, activate_ot_event, close_ot_event, grant_ot_access, revoke_ot_access, approve_ot_submission, reject_ot_submission, delete_ot_submission, save_ot_availability |
workspace:write | set_module |
reports:read | get_missed_reports, list_report_templates, get_report_template, list_report_submissions, get_report_submission, get_report_leaderboard |
reports:write | create_report_template, update_report_template, set_report_template_active, delete_report_template, submit_work_report, dismiss_report_notices, notify_missed_reports, silence_missed_report, unsilence_missed_report, set_missed_report_banner |
tickets:read | list_tickets, get_ticket |
tickets:write | create_ticket, reply_to_ticket |
notes:read | get_my_note |
notes:write | set_my_note |
How restrictions combine
Restrictions intersect. A token's real permissions are:
granted scopes ∩ what your live workspace role allows ∩ (read-only ? reads only : everything)Every layer can only narrow, never widen. A scope is a ceiling the token cannot exceed, not a permission: holding schedule:write as a member does not let you change the roster.
Roles are checked live
Your role is looked up on every call, not stored on the token. Demote a manager to member and their existing tokens lose staff powers on the very next request. Promote a member and their tokens gain staff powers for the scopes they already hold; to use staff-only scopes such as team:write, edit the token in Settings → API & MCP and tick them. No new token is needed. A call your role does not allow is refused with forbidden.
Scopes agents are offered
Agents (the member role) are not offered scopes that only staff tools use, and those scopes are dropped if requested anyway, including when an owner or lead edits an agent's token. The filter follows the role of the person who owns the token:
| Not offered to agents | Why |
|---|---|
agents:write, team:read, team:write | Agents and the team are managed by the owner, leads and managers |
schedule:write, holidays:write | Only staff change the roster and the holiday calendar |
tickets:read, tickets:write | Support tickets are for the owner, leads and managers |
workspace:write | Only staff turn modules on or off |
Agents can still use every read scope (except team:read and tickets:read) and leaves:write, ot:write, reports:write and notes:write for their own leave, OT availability, work reports and notepad. Older agent tokens that already hold a staff-only scope keep it, but every call it would allow is refused by the role check.
What each write scope lets each role do
| Scope | Owner, manager, lead | Member |
|---|---|---|
schedule:write | Assign and clear roster hours, and edit agents' weekly templates | Nothing — only managers, leads and the owner change the roster |
leaves:write | File, approve, edit and delete leave, and set balances | Request and cancel your own leave |
ot:write | Create and run OT events, grant access and review submissions. Only the owner and leads can delete an OT submission | Submit your own OT availability (needs a linked agent and access to the event) |
agents:write | Create agents, and edit, deactivate or delete agents not linked to someone ranked at or above you | Nothing — agents are managed by managers, leads and the owner |
team:write | Add, change, link and remove people ranked below you: the owner: leads, managers and members; a lead: managers and members; a manager: members | Nothing — the team is managed by managers, leads and the owner |
holidays:write | Add, change and delete holidays and holiday groups, and import presets | Nothing — holidays are managed by managers, leads and the owner |
reports:write | Manage report templates and send reminders; the owner and leads can also silence missed reports and switch the banner. Staff can submit their own reports too if linked to an agent | Submit your own work reports and dismiss your notices (needs a linked agent) |
tickets:write | Open tickets and reply to them | Nothing — tickets are handled by managers, leads and the owner |
notes:write | Replace your own notepad | Replace your own notepad |
workspace:write | Turn modules on or off (plan-locked modules cannot be changed) | Nothing — modules are managed by managers, leads and the owner |
Team and agent writes also follow a rank: owner > lead > manager > member. You can only act on people ranked below you and give roles below your own; nobody can change the owner or their own role or remove themselves. list_team / GET /team return assignable_roles and per-person can_change_role, can_link_agent and can_remove flags. The same rules apply in the dashboard, and the agent limit follows the workspace owner's plan.
Tokens created before the team tools existed do not have team:read or team:write: add them in Settings → API & MCP to use the team tools.
Tokens created before work reports, tickets, the notepad and module management were added do not have reports:write, tickets:read, tickets:write, notes:read, notes:write or workspace:write: add them in Settings → API & MCP to use those tools and endpoints.
Reads follow the same rule. ot:read lets staff see every OT event, its submissions and slot coverage; a member sees only the OT events their linked agent has access to, and their own availability.
If the OT, Leave management, Holiday calendar or Work reports module is off for the workspace, or the plan does not include it, those calls fail with feature_unavailable.
TIP
Use whoami (MCP) or GET /me (REST) to see exactly what the connected user can do right now.
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 |
| Running OT events | agents:read, ot:read, ot:write |
| Submitting your own OT hours | ot:read, ot:write — a member with a linked agent |
| A dashboard or reporting integration | Read-only, every :read scope |
| Managing the team and agents | agents:read, agents:write, team:read, team:write — staff only |
| Full agent assistance | Read and write, all scopes — only useful for owners, managers and leads; members' writes are limited to their own OT availability and leave requests |
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