Scope Policies

How scopes work

Every provider defines OAuth scopes that govern its API operations. Gmail has gmail.readonly (view emails), gmail.send (send emails), and gmail.full (read, compose, send, and permanently delete emails).

When an agent calls an API through the proxy, Gamut matches the request's method and path against the provider's scope map, more than 4,000 endpoint-to-scope mappings across the provider directory. GET /gmail/v1/users/*/messages maps to gmail.readonly and gmail.modify. The policy resolver then decides what happens.

Risk labels

Every scope carries a risk label:

• read: retrieves data without changing anything.
• write: creates or modifies data.
• destructive: deletes data or performs hard-to-reverse operations.

Set one default tier per label, such as allow all reads, review writes, and block destructive operations, instead of configuring rules scope by scope. The policy editor groups scopes by label, and review prompts offer label-wide shortcuts.

Policy decisions

• Allow: The request proceeds immediately. Suits operations the agent can perform autonomously, like gmail.readonly checks for new mail.
• Review: The request pauses until you approve or deny it. The agent waits up to 5 minutes; with no response, the request times out and the agent receives an error. Suits gmail.send, so outgoing email can be checked first.
• Block: The request is rejected outright and the agent receives a policy error. Suits scopes like gmail.full that permit permanent deletion.

Resolution order

For each matched scope, the first rule that exists wins:

1. Explicit scope policy: a rule for that specific scope, such as gmail.send set to review.
2. Risk-label default: the account's default for the scope's label (*read, *write, or *destructive).
3. Account default: the account-wide default (the * entry).
4. Global default: the fallback from user settings. The factory default is review.

When a request matches multiple scopes with different outcomes, the most permissive decision wins: a request matching both gmail.readonly (allow) and gmail.modify (review) is allowed.

Configuring scope policies

In the policy editor

1. Open Settings > Connections and select the account to open its detail page.
2. Open the policy editor. It shows the account default, one default tier per risk label, and every scope grouped by label, each with a description of what it grants.
3. Set entries to Allow, Review, Block, or Default (inherit from the next level up), then save.

From a review prompt

When a request triggers a review, the prompt in the session offers more than approve and deny:

• Always allow: sets an explicit allow policy for the matched scopes. Other pending reviews for the same agent and scopes resolve as allowed.
• Allow all read (or write, or destructive): sets the account's default for that risk label to allow, ending future reviews for every scope with the label.

Approving requests this way builds policies up during normal use, with no upfront configuration.

Scope descriptions

Each scope in the editor shows a description from official provider documentation. GitHub's repo scope reads "Grants full access to public and private repositories: code, commit statuses, invitations, collaborators, deployments, and webhooks." Review prompts use a more specific endpoint-level description when one exists, such as "Gets the specified message".

Audit trail

Every decision lands in the proxy audit log as allow, approved_by_user, denied_by_user, block, or review_timeout. See Audit Logging.

Related

• Connected Accounts: How accounts are set up and how the proxy works.
• MCP Tool Policies: The per-tool equivalent for MCP servers.