Skip to main content
A grant is scoped to a pod and the members allowed to use it, and can expire or be revoked. It is a server-enforced capability record: it connects a connector installation to a target, the tools that target may use, and the audience that may redeem the capability. It is not a credential. It does not contain a secret, and revoking it does not replace the credentials held by the connector.

The grant lifecycle

  1. A connected integration owns the connection and its connector capability.
  2. The connection owner creates a root grant for a pod.
  3. The grant names the allowed tools, write mode, audience, budget, and expiry.
  4. An installed agent may attenuate a usable grant into a narrower child grant.
  5. The broker checks the grant before each tool call and records the outcome.
  6. The connection owner can revoke a grant; revocation cascades to its children.
The root-grant route accepts connected GitHub App installations and supported hosted MCP connections, including Linear. Linear exposes only read tools. Every root grant, Linear included, works only in an eligible private pod. The server derives the installation and broker from the connection, rather than trusting those values from the request body.

Targets and audience

A grant targets a pod:
Pod grants default to the target pod’s current members. A caller can provide a smaller audience, but every listed identity must still be a current member of the pod. The read boundary follows the pod. Anyone who can view the pod can inspect a grant and its call trail. Older seat-targeted grants may appear in the list; only the connection owner and that seat can read them. The API returns an effective audience rather than exposing a stale raw membership snapshot.

Grant records

The projected grant record can include:
  • the grant and parent/root identifiers;
  • the pod target and effective audience;
  • allowed tools, write mode, and call budget;
  • creation, expiry, and revocation state; and
  • the installation identity and the connection owner who granted it.
The projection omits the connection and broker identifiers. A grant read is capability metadata, not a way to retrieve connector credentials.

API workflow

Use a human JWT for connection-owner and pod-management operations. Use the agent runtime token only for operations available to an installed agent.

Inspect grants in a pod

Anyone who can view the pod can list the grants targeting that pod:

Create a root grant

The connection owner creates a grant by naming the connection, target, tools, and optional limits. installationId and brokerId are server-derived and must not be supplied by the caller:
expiresAt is required and must be a future time. The server verifies connection ownership, target membership, enabled tools, and audience scope before returning the new grant.

Read a grant and its call trail

Anyone who can view the pod can read a grant and its call trail:
Each connector call through a grant is recorded. The record keeps a digest of the arguments, not the arguments themselves. A call record includes the tool, outcome, reason, approval identifier, timing, and an argument digest.

Attenuate or revoke

An installed agent can delegate a narrower child grant under the same pod eligibility rule. The child cannot widen the parent’s tools, audience, write mode, budget, or expiry:
The connection owner can revoke a grant directly or through the explicit revoke action. Both forms cascade to descendants:

Grants, credentials, and connectors

These records have separate jobs: Keep actual secrets in the deployment’s approved secret manager. Use Connectors to connect an integration, and Agent Tools for the runtime-facing tool surface.