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.
Base URL
All REST endpoints use:
https://app.getdrum.com/api/v1/
Create an API token
In Drum, open Settings > API Tokens.
Create a token for the user and account the integration will use.
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.
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 |
|
|
|
|
|
|
|
|
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 | A project read permission: |
Update an opportunity |
|
Convert an opportunity | Opportunity update access plus |
Read project costs |
|
Create a project cost |
|
Read project statuses or lead scores | No additional record permission |
Read cost types or finance accounts |
|
Read companies |
|
Read members |
|
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.
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_readapi_createread_all_projectsupdate_all_opportunitiescreate_projectsview_opportunity_financial_valuesonly when the integration sendsbudget_cents
For an integration that creates costs, the typical permission set is:
api_readapi_createread_all_projectsread_costscreate_costsread_account_usersonly when it creates staff costsview_project_metricsonly 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 | 300 requests per minute for each account token |
| 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.
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.