Authorization: who may call which tool
Authorization is on by default and needs no setup. Every tool call is checked before it runs, and every tool listing shows a caller only the tools it may call. You decide who may call what in the terms ToolMesh already knows from authentication: users, roles, plans and companies.
The engine is OpenFGA. ToolMesh runs it inside its own process and keeps its data in authz.db in the data directory, so there is no extra service to install or operate.
For rights a task needs only for a while, define kits: a person grants them on request, for a limited time, and signs the approval.
What is checked
Section titled “What is checked”- every direct tool call,
- each
api.*call inside a Code Mode script, - every tool listing (
tools/list,discover_tools,toolmesh.discover): a caller sees only what it may execute.
The check runs before credentials are injected and before the backend is called. A denied call returns an error result and is audited with the status denied. The check is fail-closed: if it cannot be answered, the call is denied.
TOOLMESH_AUTHZ_MODE selects how the check is answered:
| Mode | Behavior |
|---|---|
embedded (default) | ToolMesh answers the checks itself. Grants come from a preset or from config/authz.yaml. |
external | Checks go to an OpenFGA server you operate. ToolMesh only reads from it. |
disabled | No checks. The only way to switch authorization off; reported at every start and recorded in the audit trail. |
Presets
Section titled “Presets”Without a grants file, a preset decides who may call what:
| Preset | Who may call what |
|---|---|
single-user | The owner (TOOLMESH_AUTH_USER, default owner) and every caller with the role admin: every tool. Nobody else: nothing. |
team | As single-user, plus plan pro: every tool; plan free: every tool whose DADL access classification is read. |
open | Every authenticated caller: every tool. Reported as a relaxed control at every start. |
The grants come from the first of these that applies:
- the grants file (
config/authz.yaml), when it exists; - the preset named in
TOOLMESH_AUTHZ_PRESET; - the preset
open, for an installation upgraded from a version without authorization; - the preset
teamwhenusers.yamlorapikeys.yamlexists, otherwisesingle-user.
The single password or API key from the Quick Start logs in as user owner with plan pro and role admin, so every preset lets that caller use every tool. A fresh installation works without any authorization setup; other callers get nothing until a grant names them.
The log line authorization policy applied shows which preset is in effect, where the grants came from (file, env, upgrade, default) and how many there are.
Grants: config/authz.yaml
Section titled “Grants: config/authz.yaml”For finer control, copy config/authz.yaml.example to config/authz.yaml:
preset: single-user # optional: start from a preset and add to it
grants: - plan: pro backends: [github, deepl] - plan: free access: [read] - role: support tools: [zammad_list_tickets, zammad_get_ticket] - company: acme backends: [netbox] - user: alice all_tools: true
denies: # optional: blocks that win over every grant - user: alice tools: [stripe_create_refund] - role: contractor backends: [stripe]Each grant names exactly one subject:
| Subject | Who it means |
|---|---|
user: <id> | One user: username in users.yaml, user_id in apikeys.yaml, or TOOLMESH_AUTH_USER |
role: <name> | Every caller with this role: roles in users.yaml or apikeys.yaml, TOOLMESH_AUTH_ROLES |
plan: <name> | Every caller on this plan: plan in users.yaml or apikeys.yaml, TOOLMESH_AUTH_PLAN |
company: <id> | Every caller of this company: company in users.yaml, company_id in apikeys.yaml |
everyone: true | Every authenticated caller |
And at least one target:
| Target | What it allows |
|---|---|
all_tools: true | Every tool, including tools of backends added later |
backends: [...] | Every tool of these backends, by their name in backends.yaml (echo for the built-in tools) |
tools: [...] | Single tools, by their full name <backend>_<tool> |
access: [...] | Every tool whose DADL access classification is one of these (read, write, admin, dangerous, or a custom value) |
A backends grant covers the backend a call is actually routed to: with the backends web and web_search, a grant on web does not cover web_search_query.
There is nothing to keep in sync. Roles, plans and companies stay where you configure them today; a user who is moved to another plan in users.yaml is checked against the grants of that plan with the next call.
Denies
Section titled “Denies”A deny has the same form as a grant and blocks what it names for its subject, whatever any grant or the preset allows: a deny always wins. Use it to take single tools or backends away from a subject that otherwise has all of them, for example alice above, who keeps every tool except stripe_create_refund. A denied tool is refused with an error, audited as denied, and no longer listed for that caller. Only the grants file has denies; presets have none.
Changes to the file
Section titled “Changes to the file”ToolMesh reads the file at startup and again within a few seconds of every change, including when it is created or removed. Calls that start after a change has been applied are checked against the new rules; while a change is applied, no call is allowed that neither the old nor the new rules allow. A file that does not parse, or a grant or deny without a subject or a target, stops the server at startup; on a later change it is reported in the log and the rules stay as they were.
A kit is a named bundle of tools that a caller is granted as a whole and for a limited time, defined in the same file under kits:, for example everything a network diagnosis needs to read. A kit allows nothing by itself: the agent asks for it with request_grant, an approver listed under approvers: grants it on the approval page with a signature or on the approver API, and the grant ends by itself. Discovery lists the tools a kit covers marked grant_required, a denied call names the kits that would allow it, and tell_me_my_rights tells a caller what it may do and which kits would cover the rest. A deny wins over a kit as over every grant. The whole path, from the definition to the audit entry, is on Kits and approvals.
DADL access classes
Section titled “DADL access classes”DADL tools declare an access classification, which the access target of a grant refers to:
| Level | Meaning |
|---|---|
read | Read-only operations |
write | Create/update operations |
admin | Administrative operations |
dangerous | Destructive or irreversible operations |
| custom | Extendable with any string value |
Tools without a classification, which includes most tools of MCP backends, are not covered by an access grant. Grant them by backend or by name.
Upgrading from a version without authorization
Section titled “Upgrading from a version without authorization”Up to version 0.4, authorization was off unless OPENFGA_MODE=restrict was set. So that an upgrade locks nobody out, ToolMesh recognizes such an installation on the first start of the new version: when TOOLMESH_AUTHZ_MODE is not set and either OPENFGA_MODE=bypass is set or the data directory already holds data from an earlier run. It then keeps every tool open to every authenticated caller (preset open) and says so at every start, until you set TOOLMESH_AUTHZ_PRESET or write config/authz.yaml.
To have an upgraded installation start with the restrictive defaults instead, set TOOLMESH_AUTHZ_MODE=embedded before its first start on the new version, or set TOOLMESH_AUTHZ_PRESET.
OPENFGA_MODE is deprecated. It is read only while TOOLMESH_AUTHZ_MODE is not set: restrict selects external, bypass selects embedded. ToolMesh logs a warning while it is set; remove it from .env.
Operations
Section titled “Operations”- Data directory. It must be writable and should be persistent, as it is in the shipped
docker-compose.yml(./data). - Backups. Back up
authz.dband the marker file.authz-bootstrapwith the rest of the data directory. The grants are written from your configuration at every start, so a lostauthz.dbis created again without losing anything; the marker file keeps the upgrade decision of the first start. - One process per data directory. Two ToolMesh instances must not share one
authz.db. - Cost. A check takes about 0.5 to 0.6 ms. Tools without grants or denies of their own that share a backend and access classification are decided together, so filtering a listing of 3,000 tools takes about 115 ms.
External mode
Section titled “External mode”TOOLMESH_AUTHZ_MODE=external sends every check to an OpenFGA server you operate, for example one that several applications share:
TOOLMESH_AUTHZ_MODE=externalOPENFGA_API_URL=http://openfga:8080OPENFGA_STORE_ID=your-store-idToolMesh only reads from that server: it writes neither a model nor tuples, and presets and config/authz.yaml do not apply. Each check asks whether user:<user ID> has the relation can_execute on tool:<backend>_<tool>; the model and the tuples are yours. config/openfga/ in the ToolMesh repository holds an example model, tuples and a setup script, and docker-compose.yml contains commented-out OpenFGA services for this mode.
Disabling authorization
Section titled “Disabling authorization”TOOLMESH_AUTHZ_MODE=disabled is the only way to switch the checks off. Every authenticated caller may then call every tool; authentication still applies. ToolMesh reports it in the security-posture summary at every start and records an audit entry with the status authz_disabled (tool toolmesh_authz), so the audit trail shows from when on calls went unchecked.
Caller class
Section titled “Caller class”Grants decide by who the caller is, not by which client it uses. To restrict what a class of clients may do, for example to let untrusted callers run only read tools whatever their plan allows, use an Output Gate policy on ctx.user.callerClass. The ToolMesh repository ships config/policies/examples/prod-access-by-caller-class.js, a pre-execution policy that lets a call through only when the caller’s class may use the tool’s DADL access class and denies unknown classes and unclassified tools with a reason that names tool and class. Such a policy yields to a kit the caller holds, because an approver has decided for this caller and this kit; see Policies and kits.