Skip to main content

How permissions work

A permission grants an agent the right to perform one or more actions on a resource. theAuth evaluates permissions at call time by checking whether any of the agent’s permissions match the requested resource and include the requested action, then verifying all constraints pass.
string
Colon-separated resource path. A * segment matches the rest of the path from that position on.
string[]
The actions this permission grants. No fixed set, define what fits your tools.
PermissionConstraints
default:"undefined"
Optional conditions that must all be satisfied for the permission to apply.

Matching rules

Resource pattern matching

Resources follow a colon-separated hierarchy. The resource field in a permission is matched against the resource in the authorization request using exact matches or wildcards.
A * segment is not a single-segment wildcard. When the matcher reaches a * segment in the pattern, it stops comparing and accepts the resource, so the wildcard covers every remaining segment (including none). mcp:github:* matches mcp:github:repos and also mcp:github:repos:comments and mcp:github itself. Without a wildcard, the pattern and the resource must have the same number of segments. Use * only as the last segment. A wildcard in the middle, such as mcp:*:repos, also accepts everything after mcp:, so it is not a “any server, repos only” pattern.

Actions

Actions describe what the agent can do to a resource. theAuth does not enforce a fixed set, you define what makes sense for your tools. Common actions in MCP contexts: An authorization check passes when an agent has a permission with: a matching resource pattern, the requested action in that permission’s actions array, and all constraints satisfied. Only the first permission whose resource and action match is evaluated: if its constraints fail, later matching permissions are not tried.

Path matching (opt in)

Resources that are paths, such as ROS 2 names (ros2:/fleet/robot1/cmd_vel), have no way to say “one level” or “anything below” with the colon rules, because a * inside a segment is plain text. Turn on path matching and / becomes a separator inside each colon segment:
The rules, in full:
  • * matches exactly one path segment, ** matches one or more. Only a whole segment is a wildcard, r* is literal text.
  • A wildcard never matches an empty segment, . or .., so ros2:/fleet/a/../../admin cannot slip through ros2:/fleet/**.
  • A path wildcard never crosses a :. Matching is case sensitive and nothing is percent decoded.
  • A colon segment that is exactly * and comes last keeps its old meaning (it covers the rest). Before the last segment it now matches exactly one segment, so mqtt:a:*:b no longer grants mqtt:a:x:anything.
  • MQTT + and # are not aliases. A topic level is a colon segment, see the device resource names in IoT devices.
The mode applies to authorize(), delegation checks, the policy engine and its taint rules, simulate, explain, device bundles (the signed bundle carries the mode, so an offline device decides like the server) and the token vault. policy.resourceMatching overrides the top level value for the unified policy engine alone. Leave both unset and nothing changes: every existing grant matches exactly as before. Patterns without a * or ** path segment behave the same in both modes. Delegation uses the same matcher: a child resource is a subset of a parent resource when the parent pattern matches it, so ros2:/fleet/* can delegate ros2:/fleet/r1 but not ros2:/fleet/**.

Constraints

Constraints add conditions to a permission. All conditions must be met for the permission to apply.
number
default:"undefined (no limit)"
Rolling one-hour limit per agent and resource, counted in 5-minute buckets. Calls beyond it are denied with a reason starting Rate limit exceeded.
string[]
default:"undefined (any arguments allowed)"
Regular expression strings (compiled with new RegExp). Every string value in the request’s arguments must match every pattern. Non-string values are ignored, and the check is skipped when the request has no arguments.
boolean
default:"false"
When true, the call is always denied with the reason This action requires human approval before execution. Your app must handle the approval flow.
{ start: string; end: string }
default:"undefined (any time)"
HH:MM format, compared as strings against the server’s local time (not UTC). Calls outside this range are denied. Ranges that wrap past midnight are not supported.
string[]
default:"undefined (any IP)"
Exact IPv4 addresses or IPv4 CIDR ranges. Requests from IPs outside this list, or with no ip on the request, are denied. IPv6 is not supported.
Limits how many times an agent can call a resource per hour. Uses a 5-minute sliding window.
Calls beyond the limit return allowed: false with a reason such as Rate limit exceeded: 20/20 calls per hour for resource "mcp:deploy:staging". The permission engine writes these denials to the audit log with result: 'denied'; it does not write rate_limited.
Restricts what arguments an agent can pass to a tool. Patterns are regular expressions tested against each string value in the arguments field of the authorization request. Every string value must match every pattern, so use one alternation pattern rather than several alternatives.
If any string argument fails any pattern, the call is denied.
Prevents automatic authorization. The call is logged and denied until a human approves it through your application’s approval flow.
The authorization result has allowed: false and the reason This action requires human approval before execution. Your application is responsible for presenting the approval UI and re-authorizing after approval.
theAuth does not ship an approval UI. It provides the enforcement point. How you build the human review step is up to you.
Restricts when an action is allowed. Times are in 24-hour HH:MM format and are compared with the server’s local clock, not UTC. A window that wraps past midnight (for example 22:00 to 06:00) is not supported.
Calls outside the window return allowed: false. Useful for business-hours-only policies or maintenance windows.
Restricts which source IPs can use the permission. Accepts exact IPv4 addresses and IPv4 CIDR notation.
Pass the caller’s IP as ip on the authorization request (authorize(agentId, { action, resource, ip })). context.ip is only used for audit logging. Requests with no ip, or from IPs outside the list, are denied.

Permission templates

theAuth ships named templates for common patterns. Import them from @glinr/theauth:
Available templates: Templates are plain Permission[] arrays. Spread and extend them directly:
Use getPermissionTemplate(name) when you need a deep copy rather than a reference to the shared array:
Spreading directly from permissionTemplates gives you a reference to the original array entries. If you mutate the objects after spreading, you will modify the template. Use getPermissionTemplate when you need to modify entries.

Typed permissions

Declare a catalog with definePermissions and pass it as permissions to createTheAuth. The returned instance narrows resource and action on authorize, authorizeByToken, agent.create, agent.update and delegate, so typos become compile errors.
Rules:
  • Actions are correlated with the pattern that covers the resource. execute is valid for tool:file_read but not for mcp:github:issues.
  • A trailing * accepts any suffix. An exact pattern accepts only that literal resource.
  • In agent.create, agent.update and delegate, actions: ['*'] is always allowed.
  • A catalog entry of '*' makes resource collapse to string for that entry.
  • Without permissions, nothing changes and every value stays string.
  • The catalog is type level only. It is not enforced at runtime.
The typed instance is a TypedTheAuth<C> facade. To pass it to an adapter that expects TheAuth, cast it: theauth as unknown as TheAuth. The cast is sound because the typed methods only narrow their inputs. explain(agentId, action, resource) is typed the same way, with action and resource correlated.

Next steps

Delegation chains

Delegate permission subsets to other agents.

Audit trail

See how permissions are logged on every call.

Compliance

Map permissions to EU AI Act and NIST requirements.
Last modified on October 19, 2026