Skip to main content
A scope is a permission granted to an API key when it is created. Every /v1 operation lists the scopes it requires, and the server checks them on every request.

​
How scopes work

  • Colon form. API scopes are written area:read (for example inventory:read). Team member permissions use a dot form (inventory.read); the server translates one into the other with a fixed table, shown below.
  • All required scopes must be present. If an operation requires a scope the key does not hold, the answer is 403 with the code api_keys.scope_missing. The response does not say which scope is missing.
  • No wildcard. There is no “all” scope and no platform key. A key without scopes cannot exist.
  • Nothing is implied. catalog.cost:read is never granted by catalog:read; a key that needs costs must carry both.
  • Read only. Every scope is a read scope. The only write on /v1, POST /v1/analytics/exports, is covered by analytics:read.
  • Fixed for the life of the key. Scopes cannot be added to or removed from an existing key. Request a new key with the scopes you need and revoke the old one (see Rotate a key).
  • GET /v1/me needs no scope. Use it to see the scopes of a key.

​
The scopes

​
How analytics reads other data

To compute its figures, an analytics operation reads orders, stock and deliveries on the server with read access limited to that computation. It never exposes a cost, an order value or a patient reference, and it does not open the other operations to the key: a key with only analytics:read still receives 403 on GET /v1/orders.

​
What no scope grants

​
OAuth scopes on MCP

The MCP endpoint /mcp uses OAuth, not the API key used by /v1. A tool runs only when the Connected App received the scope and the signed-in member still has the matching permission. Otherwise it returns common.forbidden. See MCP tools and MCP resources.

​
A key is not a team member

The mapped permission is what the server checks, but a key differs from a person who holds the same permission:
  • A key reads every location and warehouse of its dental clinic. The location and warehouse access you set for members in Team does not apply to it.
  • A key never sees order values or patient references, even though an owner can grant those permissions to a person.
  • A key depends on the member it was created for: see The key depends on its member and its dental clinic.

​
Least-privilege recipes

Ask only for the scopes the integration uses. Each extra scope widens what a leaked key would expose.
Use a separate key for each integration, even when two integrations need the same scopes. You can then revoke one without touching the other, and each has its own rate limit budget.