Scopes and Permissions

Overview

Every API token carries a set of scopes that determine which operations it can perform. Endpoints check scopes before processing requests — a token without the required scope receives a 403 Forbidden response with the missing scopes listed.

Scope Reference

Chat and Channels

Scope	Description	Used By
channels:read	List channels, view metadata	GET /bot/channels
channels:history	Read message history (non-E2EE channels only)	GET /bot/channels/:channelId/messages
channels:write	Create channels	Channel creation endpoints
channels:manage	Archive channels, add/remove members	Channel management endpoints
messages:write	Post messages as the bot	POST /bot/channels/:channelId/messages
reactions:write	Add and remove reactions on messages	Reaction endpoints

Users

Scope	Description	Used By
users:read	View user profiles (name, avatar, role)	GET /bot/users
users:read:email	Include email addresses in user data	GET /bot/users (adds email field)

Calls

Scope	Description	Used By
calls:read	View call metadata (title, duration, participants)	Call listing endpoints

Files and Drive

Scope	Description	Used By
files:read	Download files (legacy — prefer drive:read)	Legacy file endpoints
files:write	Upload files (legacy — prefer drive:write)	Legacy file endpoints
drive:read	List folders, view file metadata, download files	GET /bot/drive/folders/:folderId
drive:write	Upload files, create/rename/delete folders	POST /bot/drive/folders

Tasks

Scope	Description	Used By
tasks:read	View projects, tasks, and comments	GET /bot/tasks, GET /bot/tasks/:taskId, GET /bot/tasks/projects
tasks:write	Create, update, complete, and delete tasks and projects	POST /bot/tasks, PATCH /bot/tasks/:taskId, DELETE /bot/tasks/:taskId, POST /bot/tasks/projects

Calendar

Scope	Description	Used By
calendar:read	View calendar events and scheduled calls	GET /bot/calendar/events
calendar:write	Create, update, cancel events, RSVP	Calendar write endpoints

Mail

Scope	Description	Used By
mail:read	View mailbox metadata (subject, sender, date — never body content)	GET /bot/mail/threads

Teams

Scope	Description	Used By
teams:read	List teams, view members	GET /bot/teams, GET /bot/teams/:teamId
teams:write	Add/remove team members, update team settings	POST /bot/teams/:teamId/members, DELETE /bot/teams/:teamId/members/:userId

Admin Scopes

Admin scopes require the service account creator to have the ADMIN role in the organization. Non-admin users cannot create tokens with these scopes.

Scope	Description
admin:users	Manage users (invite, deactivate, change roles)
admin:channels	Manage all channels regardless of membership
admin:audit	Read organization audit logs

How Scope Checking Works

Single Scope Requirement

Most endpoints require a single scope. For example, GET /bot/tasks requires tasks:read:

# Works with tasks:read scope
curl -H "Authorization: Bearer mak_..." \
  "https://app.mandraki.cloud/api/v1/orgs/{orgId}/bot/tasks"

Alternative Scopes

Some endpoints accept alternative scopes. For example, GET /bot/drive/folders/:folderId accepts either drive:read or files:read (the legacy equivalent):

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Requires one of these scopes",
  "required": ["drive:read", "files:read"]
}

Scope Errors

When a token lacks a required scope, the response includes the missing scopes:

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Insufficient scopes",
  "missing": ["tasks:write"]
}

Resource Scopes

Resource scopes restrict a token to operate only on specific resource instances. They are configured at token creation time and cannot be changed after creation.

Available Resource Types

Resource Type	Restricts	Example
teams	Which teams the token can access	["team-uuid-1", "team-uuid-2"]
channels	Which channels the token can read/write	["channel-uuid-1"]
projects	Which task projects the token can access	["project-uuid-1"]
folders	Which Drive folders the token can access	["folder-uuid-1"]

Behavior

• Omitted or empty: No restriction — the token can access all resources of that type (within its scopes).
• Populated: The token can only access the listed resource IDs. Requests targeting other resources return 403:

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "API token does not have access to this team"
}

Example: Narrowly Scoped Token

A token that can only read tasks in one project and post messages to two channels:

{
  "label": "Sprint bot",
  "scopes": ["tasks:read", "messages:write", "channels:read"],
  "resourceScopes": {
    "projects": ["b7e1c2a3-..."],
    "channels": ["a1b2c3d4-...", "e5f6a7b8-..."]
  }
}

Recommended Scope Sets

Read-Only Dashboard

["tasks:read", "teams:read", "channels:read", "users:read", "calendar:read"]

Task Automation Bot

["tasks:read", "tasks:write", "channels:read", "messages:write", "users:read"]

Channel Notification Bot

["channels:read", "messages:write"]

Full Admin Integration

["tasks:read", "tasks:write", "teams:read", "teams:write", "channels:read",
 "channels:history", "messages:write", "drive:read", "drive:write",
 "calendar:read", "users:read", "users:read:email",
 "admin:users", "admin:channels", "admin:audit"]