Join us June 23 for a look at the business impact of identity-based connectivity.REGISTER ->

How Aperture grants work

Last validated:

Aperture by Tailscale is currently in beta.

Aperture controls which users and groups can access which models and MCP capabilities through grants. This topic explains the model behind grants so you can reason about access before you write configuration. For step-by-step instructions, refer to the grant how-tos linked under Next steps.

The grants model

Aperture grants build on the Tailscale grants framework, so they inherit two properties that shape everything else:

  • Deny-by-default. Without a matching grant, a user can connect to the Aperture device but cannot access any models or MCP capabilities. Access exists only where a grant explicitly provides it.
  • Additive and allow-only. Each grant only adds access. There is no deny rule. A user's effective access is the union of every grant whose src matches their identity. To take access away, you remove or narrow the grants that provide it rather than writing a rule that subtracts it.

If you are coming from Tailscale network ACLs, this is the key difference to internalize: there is no deny in grants. You express policy entirely through what you allow.

Anatomy of a grant

A grant pairs a set of identities with a set of capabilities:

{
  "grants": [
    {
      "src": ["group:ai-users"],
      "app": {
        "tailscale.com/cap/aperture": [
          { "role": "user" },
          { "models": "anthropic/**" }
        ]
      }
    }
  ]
}
  • src lists who the grant applies to. Entries can be individual users ("alice@example.com"), SCIM groups by email, or Tailscale groups ("group:ai-users"). Matching a group: entry requires visible groups.
  • app["tailscale.com/cap/aperture"] is an array of capability objects describing what the matched identities can do. Common capabilities include role (the user's permission level), models (a glob over provider/model names), and the MCP fields mcp_tools, mcp_resources, and mcp_templates. Operational fields such as custom headers, quotas, hooks, and CORS settings also live here.

For the complete list of capability fields and their syntax, refer to the grants configuration reference.

How Aperture evaluates a request

Aperture resolves access at request time using the connecting user's Tailscale identity:

  1. Identify the user. Aperture authenticates every connection through Tailscale identity, so there is no separate login step.
  2. Collect matching grants. Aperture gathers every grant whose src matches the user's login, email, or group membership.
  3. Merge capabilities. The capabilities from all matching grants combine into the user's effective access.
  4. Check the requested action. Aperture matches the requested model name against the merged models patterns (and MCP items against the mcp_* patterns), then applies the precedence rules below.
  5. Allow or deny. If a capability grants the requested access, the request proceeds. If nothing matches, Aperture denies the request, consistent with deny-by-default.

Precedence and conflicts

Because grants are additive, multiple grants commonly apply to the same user. Two resolution rules determine the outcome when they overlap:

  • Roles: the highest permission wins. If matching grants assign different roles, admin takes precedence over user. A user who matches both an admin grant and a user grant receives admin-level permissions.
  • Model patterns: the most specific glob wins. When several models patterns match a requested model, Aperture uses the most specific one. For example, "anthropic/claude-opus-4-7" beats "anthropic/**", which beats "**". When two patterns are equally specific, the entry that appears earlier in the configuration wins.

These rules apply within the additive union; they decide which matching entry takes effect, not whether to subtract access.

Groups in grants

To use group: identifiers in a grant's src, the Aperture device needs group membership information, which the Tailscale control plane does not send by default. Enable visible groups by adding the tailscale.com/visible-groups node attribute to the Aperture device in your tailnet policy file. Aperture then evaluates group membership at request time using the connecting user's identity.

Next steps