Developers

Authentication

One Bearer token per integration, with its own permissions, expiry and IP addresses.

The Authorization header

Send the token on every request in the Authorization header:

GET https://app.bm.consulting/api/v1/contacts HTTP/1.1
Authorization: Bearer bmc_live_…

Tokens start with bmc_live_. The API is served over HTTPS only; never send the token over unencrypted channels or put it in the URL.

What the API checks, and in what order

  1. The token exists, is active, is not revoked and has not expired. Otherwise it responds 401.
  2. The route accepts account-bound tokens. Otherwise it responds 403.
  3. One of the token's permissions covers the one the route requires. Otherwise it responds 403 with required_permission.
  4. The source IP is in the token's allowed IP list, if it has one. Otherwise it responds 403.
  5. Rate limits are not exceeded. Otherwise it responds 429 (Rate limits).

Scope: companies and groups

When you create the token, under Companies and groups, you choose which companies' data it can see (step by step):

  • Primary account: always one. The token uses its per-minute limits and monthly quota.
  • Other companies: those you also administer as holder or administrator that have API access enabled.
  • Whole groups: only if you choose them. A group includes all its subsidiaries, also those added later. Choosing one company of a group does not add the rest.

The scope is recomputed on every request. If the person who created the token stops being holder or administrator of a company, the token stops seeing it; if that happens on the primary account, the token stops working and the API responds 401. These changes can take up to 60 seconds to apply. GET /auth/whoami returns the companies a token reaches today.

An MCP connection made with OAuth (for example from Claude or ChatGPT) reaches a single company, the one you choose when you authorise it. For an agent that works across several companies, use a bmc_live_… token with those companies.

Token lifecycle

Creation

A token is created in the client area, under Developers › Credentials. The full token is shown only once; BMC keeps only a fingerprint that cannot be used to recover it. If you lose it, rotate it or create another.

Rotation

Rotating a token replaces its value with a new one; the previous value stops working. Update your integration with the new value. Rotate tokens periodically and whenever you suspect exposure.

Switch

Each token can be disabled and re-enabled without losing its configuration. While disabled, the API responds 401.

Revocation

Revoking a token is permanent: it stops working and cannot be re-enabled. Create a new one if needed.

Expiry

You can set an expiry date when creating the token. After that date the API responds 401. For temporary integrations, use the shortest expiry that works.

API access for the company

If BMC turns off API access for a company, the client area stops showing the Developers section and tokens can no longer be created, edited or rotated. Today, tokens and connections that already existed keep working until they expire or are revoked. To cut them, turn them off or revoke them yourself first, or ask BMC to do it.

Allowed IP addresses

A token can be restricted to a list of IP addresses or CIDR ranges, IPv4 or IPv6 (for example 203.0.113.10 or 203.0.113.0/24). With an empty list the token works from any IP. With a list, requests from any other IP receive 403.

BMC evaluates the IP with which the request reaches its infrastructure. If your server reaches the Internet through a proxy or a NAT gateway, add the proxy's outbound address, not the internal one.

MCP connections made with OAuth carry no IP list: they are controlled by the role, the expiry and the on/off switch of the connection (MCP server). A bmc_live_… token with an IP list does not work on the MCP server, because the MCP server calls the API from BMC's infrastructure and that call is rejected. To use a token with the MCP server, leave the list empty.

OAuth for the MCP server

The Bearer token is the route for server-to-server integrations. To connect an assistant or MCP client (Claude or ChatGPT, for example) you do not need to copy any token: the MCP server uses OAuth 2.1 with PKCE. The person connecting signs in to BMC, chooses the company and the role, and the connection appears in Developers › API & MCP › Credentials as a credential of type MCP. The access token lasts 1 hour and the refresh token 30 days; the client handles both. Details in MCP server and, step by step for each assistant, in Connect your AI.

Masked personal data

A token can read a resource (contacts, workers, bank accounts) without seeing the personal data it contains. If the token does not have Can see personal data ticked, resources flagged as such in the catalogue return masked values:

DataWithout personal data access
Tax ID (NIF)The first character and the last two are kept; the rest are asterisks.
IBANThe first four and last four characters are kept.
PhoneThe last three digits are kept.
Date of birthnull
Addressnull

Tick that box only on tokens for integrations that genuinely need it. It is not a catalogue permission: it is an option on each token.

Good practice

  • One token per integration, named for what it does. You can revoke one without affecting the others.
  • Grant the minimum permissions: start with Read and avoid Full unless essential.
  • Set an expiry and rotate tokens periodically.
  • Restrict the token to your servers' IPs when they are fixed.
  • Keep the token in a secrets manager or an environment variable; never in code, logs or repositories.
  • If a token is exposed, revoke it immediately and create another.
Email
Contact