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.Colon-separated resource path. A
* segment matches the rest of the path from that position on.Optional conditions that must all be satisfied for the permission to apply.
Matching rules
Resource pattern matching
Resources follow a colon-separated hierarchy. Theresource field in a permission is matched against the resource in the authorization request using exact matches or wildcards.
* 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.., soros2:/fleet/a/../../admincannot slip throughros2:/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, somqtt:a:*:bno longer grantsmqtt:a:x:anything. - MQTT
+and#are not aliases. A topic level is a colon segment, see the device resource names in IoT devices.
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.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.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.When true, the call is always denied with the reason
This action requires human approval before execution. Your app must handle the approval flow.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.
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.Rate limiting
Rate limiting
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.Argument pattern matching
Argument pattern matching
Restricts what arguments an agent can pass to a tool. Patterns are regular expressions tested against each string value in the If any string argument fails any pattern, the call is denied.
arguments field of the authorization request. Every string value must match every pattern, so use one alternation pattern rather than several alternatives.Human-in-the-loop approval
Human-in-the-loop approval
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.
Time windows
Time windows
Restricts when an action is allowed. Times are in 24-hour Calls outside the window return
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.allowed: false. Useful for business-hours-only policies or maintenance windows.IP allowlist
IP allowlist
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:
Templates are plain
Permission[] arrays. Spread and extend them directly:
getPermissionTemplate(name) when you need a deep copy rather than a reference to the shared array:
Typed permissions
Declare a catalog withdefinePermissions 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.
- Actions are correlated with the pattern that covers the resource.
executeis valid fortool:file_readbut not formcp:github:issues. - A trailing
*accepts any suffix. An exact pattern accepts only that literal resource. - In
agent.create,agent.updateanddelegate,actions: ['*']is always allowed. - A catalog entry of
'*'makesresourcecollapse tostringfor that entry. - Without
permissions, nothing changes and every value staysstring. - The catalog is type level only. It is not enforced at runtime.
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.