Help

Authentication and permissions

Every MCP request carries one credential, sent as Authorization: Bearer <token>. The credential belongs to one Drum user in one Drum account, and every tool call runs as that user.

Credential For Made in
Sign in with Drum (OAuth 2.1) Hosted clients, such as Claude and ChatGPT The client. You approve it on Drum’s consent screen
Account-scoped API token Clients you configure by hand, such as Claude Code, Cursor and VS Code, and your own agents Drum, under Profile, then API

Sign in with Drum (OAuth)

The client finds Drum’s OAuth details from the endpoint and opens Drum’s consent screen. You never copy a token.

Fact Detail
Flow OAuth 2.1 authorization code with PKCE (S256). Public clients only: no client secret
Protected resource metadata https://app.getdrum.com/.well-known/oauth-protected-resource/api/v1/mcp. A 401 from the endpoint names it in WWW-Authenticate
Authorization server metadata https://app.getdrum.com/.well-known/oauth-authorization-server
Resource https://app.getdrum.com/api/v1/mcp. A token for any other resource is refused
Client identity Claude and ChatGPT identify themselves with a client ID metadata document. Grok, Cursor and Copilot Studio register themselves, and Drum accepts only their known redirect addresses
Clients Only supported clients can connect (see Supported clients). Another client sees “This client could not be verified. Only supported AI clients can connect to Drum.”
Scopes mcp:read (read tools only) and mcp:write (write tools). A client that asks for no scope gets both
Account Each connection is bound to the one account chosen on the consent screen. Connect again to give a client a second account
Toolsets Chosen on the consent screen, and changed later on Connected Agents
Access tokens Last 1 hour and refresh automatically. A refresh token can be used once
Idle limit A connection unused for 30 days stops refreshing. Connect the client again
Reconnecting Connecting the same client to the same account again replaces the old connection
Where connections live Your user menu, Profile, then Connected Agents
Revoking Revoke on Connected Agents. All access of the client stops at once

OAuth works for the MCP endpoint only. The REST API uses API tokens.

The screen is headed Connect client to Drum. It shows:

  • Client, the name of the AI client, and Verified origin, the web address Drum checked it against
  • This connection will be able to, the access the client asked for
  • Account, to choose the one Drum account the client may use
  • Toolsets, to choose the tools it gets (see Toolsets)
  • Approve

A request that waits too long shows “This connection request has expired.” Start again from the client.

API tokens

An API token works for the MCP endpoint and the REST API. Create one under Profile, then API, and choose its toolsets on the same screen (see Create an API token).

  • The token must belong to an account. An old token with no account is refused.
  • Tokens have no scopes. What the AI can do depends on the toolsets and on the user’s role.
  • Anyone with the token can act as its user in that account. Keep it in an environment variable or a secrets store, not in a shared file or a repository.

Authentication errors

These are HTTP errors, not tool errors.

Status When
401 with WWW-Authenticate: Bearer realm="Drum", resource_metadata="...", scope="mcp:read mcp:write" The Authorization header is missing. The client should start Sign in with Drum
401 with error="invalid_token" in WWW-Authenticate The token is unknown, expired or revoked
401 {"error": "This endpoint requires an account-scoped API token. ..."} An old API token that has no account
403 {"error": "Account access revoked"} The user has been removed from the account
403 with error="insufficient_scope" in WWW-Authenticate A connection with only mcp:read called a write tool. The body is a JSON-RPC error -32600

Permissions

A tool is listed, and can be called, only when all of these allow it:

  1. The OAuth scope, for a Sign in with Drum connection. mcp:read admits only read-only tools.
  2. The API permission for the tool’s kind of work: api_read to read, api_create to create, api_update to change and api_delete to delete. Account admins pass this check. See The four API permissions.
  3. The role permissions the same work needs in the browser, such as create_costs or read_companies. Each tool page lists them under Needs.
  4. The selected toolsets of the connection or token.

The role check comes before the toolset check. A tool the role cannot use answers not_authorized whether its toolset is selected or not. A tool the role can use, but whose toolset is not selected, answers not_found with reason tool_not_selected and names the toolsets that have it.

Record checks

Each call then checks the record itself, with the same rules as the browser.

  • A record the user cannot read answers not_found, so a hidden record looks the same as one that does not exist.
  • A money field the user may not see is left out of the result.
  • Personal data comes only on request. A member row from search_records has no email or role, and get_project and get_opportunity give contacts’ email and phone numbers only when include names contacts.

A narrower assistant

An assistant can never do more than its user. To give an assistant less access than a person has, give it its own Drum user with a narrower role, and connect it as that user. See Give an assistant its own Drum user.