Scopes and sharing
A key or an OAuth grant carries a set of scopes. Each scope unlocks a fixed set of tools, or one REST surface. Access is default-deny: a token with no scopes sees no tools and can call none. The full list of scopes is in Authentication.
Statute tools #
searchStatutes and getSection are unlocked by the statutes:read scope. Keys issued before the family scope existed carry the tool names searchStatutes and getSection instead, and those still work.
Family-scoped tools #
Every other tool is unlocked by a family scope. A family scope unlocks every tool in its row, and nothing else.
| Scope | Tools unlocked |
|---|---|
citation:verify |
verifyCitation, checkSourceExists, scoreConfidence |
benchmark:read |
compareLaws |
gap:read |
identifyGaps, scoreAlignment |
gap:issue |
issueGapReport, which issues a frozen gap report and is metered. See Usage and units. |
skills:read |
listSkills |
skills:trigger |
triggerWorkflowRun |
documents:write |
parseDocument |
matters:read |
listMatters, getMatter, getMatterDocuments, getMatterConversations |
matters:read returns the matters the key's owner is a member of. Add the owner to a matter to expose it to the key. Organisation-wide reads are not available through keys.
gazette:read and draft:generate are deprecated. Keys that carry them still validate, and they unlock no tool.
REST-only scopes #
These gate REST routes, not tools, so they unlock nothing over MCP.
| Scope | Grants |
|---|---|
runs:read |
GET /api/v1/runs/{id} |
webhooks:read |
GET /api/v1/webhooks and GET /api/v1/webhooks/{id}/deliveries |
webhooks:write |
Register, rotate, delete and replay webhook endpoints and deliveries |
usage:read |
GET /api/v1/usage, for workspace owners and admins |
How a call is checked #
For each request, the server works out which tools the token's scopes allow, and refuses any call outside that set. The check runs on the server for every transport, so a client cannot widen its own access by asking for more. A refused call gets 403 with "code": "tool_not_enabled_for_key".
A scope with no tools behind it unlocks nothing. That is deliberate: a new scope does nothing until it is mapped to tools.
One catalogue #
The server keeps one list of the 15 exposable tools, and both REST and MCP read from it. The tool catalogue documents each one.
Sharing on the key page #
Owners and admins set a key's scopes under Sharing Controls on the workspace's API keys page. A new key starts with Search Statutes on. The other switches add the family scopes above. Changing a switch takes effect on the next request.
Settings that touch Matters carry a warning, because Matters content leaves Mandatum when a client reads it. Read Data egress before enabling them.