Skip to content

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.

  • 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:

ModeBehavior
embedded (default)ToolMesh answers the checks itself. Grants come from a preset or from config/authz.yaml.
externalChecks go to an OpenFGA server you operate. ToolMesh only reads from it.
disabledNo checks. The only way to switch authorization off; reported at every start and recorded in the audit trail.

Without a grants file, a preset decides who may call what:

PresetWho may call what
single-userThe owner (TOOLMESH_AUTH_USER, default owner) and every caller with the role admin: every tool. Nobody else: nothing.
teamAs single-user, plus plan pro: every tool; plan free: every tool whose DADL access classification is read.
openEvery authenticated caller: every tool. Reported as a relaxed control at every start.

The grants come from the first of these that applies:

  1. the grants file (config/authz.yaml), when it exists;
  2. the preset named in TOOLMESH_AUTHZ_PRESET;
  3. the preset open, for an installation upgraded from a version without authorization;
  4. the preset team when users.yaml or apikeys.yaml exists, otherwise single-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.

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:

SubjectWho 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: trueEvery authenticated caller

And at least one target:

TargetWhat it allows
all_tools: trueEvery 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.

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.

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 tools declare an access classification, which the access target of a grant refers to:

LevelMeaning
readRead-only operations
writeCreate/update operations
adminAdministrative operations
dangerousDestructive or irreversible operations
customExtendable 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.

  • Data directory. It must be writable and should be persistent, as it is in the shipped docker-compose.yml (./data).
  • Backups. Back up authz.db and the marker file .authz-bootstrap with the rest of the data directory. The grants are written from your configuration at every start, so a lost authz.db is 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.

TOOLMESH_AUTHZ_MODE=external sends every check to an OpenFGA server you operate, for example one that several applications share:

Terminal window
TOOLMESH_AUTHZ_MODE=external
OPENFGA_API_URL=http://openfga:8080
OPENFGA_STORE_ID=your-store-id

ToolMesh 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.

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.

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.