Every Drum REST API request uses an account-scoped bearer token. The request runs as the user who owns the token and is limited to that user's account, role and record access. The same token type can authenticate the MCP endpoint when you select MCP toolsets on the token.

Base URL

All REST endpoints use:

https://app.getdrum.com/api/v1/

Create an API token

In Drum, open Settings > API (the API Tokens page).
Create a token for the user and account the integration will use.
Under Toolsets, tick the MCP toolsets this token should serve. The default is My work.
Set an expiry date.
Copy the token and store it in a secrets manager. Drum does not show it again.

Send the token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

Send JSON request bodies with:

Content-Type: application/json

An expired or invalid token returns 401. A valid token whose user has been removed from the account returns 403.

MCP toolsets on API tokens

Each API token stores which MCP toolsets you selected. The MCP endpoint /api/v1/mcp only serves tools from that selection. Your role permissions still apply on top.

Choose toolsets when you create or edit a token under Settings > API.
The default is My work. Existing tokens keep My work until you save a wider selection.
Until you save a selection, Drum shows: "This token now uses My work. Select more toolsets for more tools."
Calling an MCP tool that is not in the selection returns reason tool_not_selected.
Above about 30 tools, Drum warns that the agent can pick the wrong tool more often. Large selections are still allowed.

For Connected Agents (Sign in with Drum) and step-by-step screens, see How to choose MCP toolsets for Connected Agents and API tokens.

Permission model

Two permission checks apply to each request:

The user's role must allow the HTTP verb.
The user must be allowed to read or change the requested record in Drum.

HTTP verb	Role permission
`GET`, `HEAD`	`api_read`
`POST`	`api_create`
`PATCH`, `PUT`	`api_update`
`DELETE`	`api_delete`

A missing verb permission returns 403 with {"error":"Insufficient API permissions"}.

A record that the user cannot read normally returns 404, so the API does not reveal that a hidden record exists. A write the user cannot perform on a visible record returns 403 with {"error":"Forbidden"}.

Account administrators bypass the verb checks and have every record permission. An administrator token therefore gives an integration full write access to the account.

Endpoint permissions

Endpoint	Required record permissions
Read opportunities	An opportunity read permission: `read_all_opportunities`, `read_team_opportunities` or `read_assigned_opportunities`. A project read permission isn't needed. List, show, update and convert all use it, so any opportunity the list returns can be opened, and a hidden one answers `404`
Update an opportunity	`update_all_opportunities`, `update_team_opportunities` or `update_assigned_opportunities`
Convert an opportunity	Opportunity update access plus `create_projects`, or instead `read_quotes` plus `accept_quotes` for the accepted proposal being converted; sending `budget_cents` also requires `view_opportunity_financial_values`
Read project costs	`read_costs` plus access to the project
Create a project cost	`create_costs` plus access to the project
Read project statuses or lead scores	No additional record permission
Read cost types or finance accounts	`read_costs`
Read companies	`read_companies`
Create companies	`create_companies`
Update companies	`update_companies`
Read contacts	`read_companies`
Create a contact	`create_companies`
Change or restore a contact	`update_companies`
Delete a contact	`delete_companies`
Link a contact to a company, opportunity or project, or remove the link	`read_companies` plus the update permission of that company, opportunity or project. See Contacts API
Read, add, change, delete or restore notes on a record	No note permission of its own: read access to that record. See Notes API
Read members	`read_account_users` or `manage_permissions`
Read the resourcing schedule	`view_global_resourcing`, or view or edit project resourcing (or a resourcing project role) on the project when you send `project_id`
Preview, apply or delete allocations	`edit_project_resourcing` (or a project role that can edit resourcing) on each change's project. Apply needs `api_create` or `api_update`, preview needs only `api_read`. Going over budget also needs `allow_over_budget_resourcing`. See Resourcing API

Financial fields are returned only when the token user has the corresponding Drum permission. For example, view_opportunity_financial_values controls the amount field on opportunities, and view_project_metrics controls cost totals. Gross profit on projects (gross_profit) needs your account's Show Gross Profit Figures setting turned on plus view_gross_profit, and doesn't need view_project_metrics. See Project list filters and gross profit in the API.

Recommended integration user

Create a dedicated integration user with a role that contains only the required permissions. Avoid using an administrator token.

For an integration that converts opportunities, the typical permission set is:

api_read
api_create
read_all_opportunities
update_all_opportunities
create_projects
view_opportunity_financial_values only when the integration sends budget_cents

For an integration that creates costs, the typical permission set is:

api_read
api_create
read_all_projects
read_costs
create_costs
read_account_users only when it creates staff costs
view_project_metrics only when it needs cost totals in responses

Add api_update only when the integration also edits opportunities. Give every token an expiry and rotate it before that date.

Rate limits

Scope	Limit
All `/api/v1/` requests	300 requests per minute for each account token
`POST /api/v1/opportunities/:id/convert`	30 requests per minute for each account

A request blocked by the API throttle returns 429 and includes a Retry-After header. Opportunity conversion can also return 409 with code rate_limited. Handle both by waiting and retrying with backoff.

Allocation changes can return 409 with code resourcing_busy when another save is working on the same allocations. A preview gives up after 3 seconds. Nothing is saved, so wait a moment and try again.

A request that has to call Xero can also return 429 with {"error": "Too many Xero requests. Retry later.", "code": "xero_rate_limited"}. That means Drum's Xero limiter refused the call before anything was sent to Xero: the organisation's share of Xero's limits is used up, or Xero asked Drum to cool down. Wait for the number of seconds in Retry-After (RateLimit-Reset gives the same time as a Unix timestamp) and try again. Before 9 October 2026 these requests could fail with a 500 instead.

Error format

Most API errors use:

{ "error": "Human-readable message", "code": "machine_readable_code" }

Validation errors may also include field or an errors array. Treat the HTTP status as the primary result and use code for program logic.

Security

Keep tokens on the server. Do not put them in browser code or mobile apps.
Do not include tokens in URLs, logs or support messages.
Store tokens in a secrets manager or encrypted environment variable.
Rotate a token immediately if it may have been exposed.
Use a separate token for each integration so it can be revoked independently.

Drum API authentication, permissions and rate limits