Authorization and Tokens

The public API is authorized using personal access tokens (PAT). A single token is tied to one account and applies to that account's builder entities within the granted scopes.

Creating a token

A personal token is created in the account dashboard, in the personal tokens section. The token value is shown only once at creation: save it somewhere safe. The server stores only a hashed version; it cannot be recovered. If you lose it, issue a new token and delete the old one.

All personal tokens start with the mbp_ prefix.

Passing the token

The token is passed in every request via the Authorization HTTP header using the Bearer scheme:

Authorization: Bearer mbp_YOUR_TOKEN

The same header is used for session-based access from the web dashboard (where it is a short-lived JWT), but for integrations always use a personal mbp_… token.

The token's account

A token works in exactly one account. By default that is your own; if somebody granted you access to their account, you can pick it when creating the token: the account_id field in the POST /api/tokens body, or the dropdown above the expiry in the dashboard. GET /api/account/cabinets lists the accounts you may choose from.

What that means in practice:

• GET /api/bots returns the bots of the selected account only: neither your own nor a third account appear in the list.
• A bot of any other account answers 404, the same answer a stranger's bot gives: the token cannot be used to test whether an id exists outside its account.
• Your rights do not change: the token narrows access to one account, it never widens it. What you may do with a bot is still decided by your member rights (the account role plus any per-bot grants).
• A token minted for somebody else's account acts with your rights in that account. The account's money (/api/billing/*) needs the account right billing.read, and creating projects needs bots.create. Full access (the * scope) does not grant account rights.
• If the access is revoked, the token stops working immediately, on the very next request. There is nothing to revoke separately.

An account reached through a bot

GET /api/account/cabinets returns a source field for each account:

• self: your own account;
• account: you were granted access to the account, and your role defines the rights;
• bot: you reach the account only through a shared bot. You hold no account rights there.

With a source: "bot" account, operations on that bot work within your per-bot rights, while anything that concerns the account as a whole is refused: connecting a bot, billing, and so on. REST answers 403 with {"error":"missing cabinet right"}, and when you are a member without the specific right: missing cabinet right: <right>. In MCP this is the tool error permission denied: missing cabinet right (for example, connect_bot needs bots.create, billing tools need billing.read or billing.write).

To fix it, the account owner invites you in the "Cabinet access" card with the required right. You do not need to reissue the token: it starts working on the next request after you accept the invitation.

Tokens issued before this feature belong to your own account. If such a token worked with a bot shared from somebody else's account, issue a separate token for that account.

Scopes

A token has a set of scopes in the format resource:action. Read operations require the :read suffix, mutations require :write. Available scopes:

• bots:read, bots:write: bots, their settings, sync, bot token.
• reactions:read, reactions:write: reactions, import, formula testing, links, ordering.
• labels:read, labels:write: subscriber labels.
• collections:read, collections:write: collections and records.
• flows:read, flows:write: flows.
• integrations:read, integrations:write: integrations, connections, credentials.
• media:write: upload to the media library.
• templates:read, templates:write: bot templates.
• settings:read, settings:write: settings.
• subscribers:read: subscribers and dialog history (read).
• broadcasts:write: broadcasts and their management.
• stats:read: stats and analytics.
• billing:read: balance and plans (read).

The special scope * grants full access to the entire public endpoint set.

What is accessible with a token, and what is not

Under a personal token, only builder endpoints are accessible: those that "help build a bot." Not accessible via PAT (web session only): sign-in and registration, mobile endpoints, payments and balance top-ups, notifications, audit log, operator message sending in a dialog, incoming webhooks and payment callbacks, WebSocket. A request with an mbp_ token to such a route will return 401 or 403.

If the token lacks the required scope for a given route, a 403 is returned. For more on error codes, see the errors guide.

Agent scopes

• managed_ai:invoke and managed_ai:usage:read: provider-neutral AI calls and usage.
• copilot:use: Copilot proposal lifecycle. Creation also needs journey:read for diagnostic modes or journey:edit for graph changes.
• journey:read and journey:edit: Flow Intelligence and Explainable Replay.
• Meta connection management uses the existing integration/bot scopes and still enforces account and per-bot rights.

MCP applies the same checks fail-closed. A tool cannot widen the PAT's cabinet or bot membership.

What's next

• API quickstart: first request with a token.
• Errors: what 401 and 403 mean.
• MCP: the same token for the agentic interface.