Gamut

Scope Policies

How to control what API scopes a connected account can use with allow, review, and block policies at the scope level.

Scope policies let you control how agents use connected accounts at a granular level. Instead of giving an agent blanket access to an entire API, you can set per-scope rules that allow, require review, or block specific categories of API operations.

How Scopes Work

Every connected account provider has a set of OAuth scopes that govern what API operations are possible. For example, Gmail has scopes like gmail.readonly (view emails), gmail.send (send emails), and gmail.full (read, compose, send, and permanently delete emails).

When an agent makes an API request through the proxy, Superagent matches the request's HTTP method and path against a scope map for that provider. The scope map contains over 4,000 endpoint-to-scope mappings across 40 providers. For example, GET /gmail/v1/users/*/messages maps to scopes like gmail.readonly and gmail.modify.

Once the scopes are identified, the policy resolver determines what to do.

Policy Decisions

Each scope can have one of three policy decisions:

Allow

The request proceeds immediately without user intervention. Use this for operations you trust the agent to perform autonomously.

Example: You might allow gmail.readonly so your agent can check for new emails without asking.

Review

The request is paused, and you receive a notification asking you to approve or deny it. The agent waits (up to 5 minutes) for your decision. If you do not respond in time, the request times out and the agent receives an error.

Example: You might set gmail.send to review so that you can verify email content before the agent sends it.

Block

The request is immediately rejected. The agent receives an error indicating the request was blocked by policy. Use this to prevent agents from performing specific operations entirely.

Example: You might block gmail.full to prevent permanent email deletion.

Policy Resolution Order

When a request matches one or more scopes, Superagent resolves the effective policy using a three-tier hierarchy:

  1. Explicit scope policy — If you have set a policy for a specific scope (e.g., gmail.send = review), that policy applies.
  2. Account default — If no explicit scope policy exists, the account-level default applies. This is configured as the * scope in the policy editor.
  3. Global default — If no account default is set, the global default from your user settings applies. The factory default is review.

When a request matches multiple scopes and those scopes have different policies, the most permissive decision wins. For example, if a request matches both gmail.readonly (allow) and gmail.modify (review), the request is allowed. This ensures that an agent is not blocked when any of the matched scopes permits the operation.

Configuring Scope Policies

From the Settings Dialog

  1. Navigate to Settings > Connections.
  2. Find the connected account you want to configure.
  3. Click the Policies button (shield icon) on the account row.
  4. The scope policy editor opens, showing:
    • Account Default — The fallback policy for scopes without explicit rules. Set to "Default" to inherit from your global settings.
    • Per-scope list — Every scope available for the provider, with its current policy and a description of what the scope grants.
  5. Use the toggle for each scope to set it to Allow, Review, Block, or Default.
  6. Click Save Policies to apply.

From a Review Prompt

When an agent's request triggers a review, the review prompt appears in the chat session. Along with the approve/deny buttons, the prompt offers an Always Allow option that sets an explicit "allow" policy for the matched scopes. This is a convenient way to build up policies as you use the agent, without needing to configure everything upfront.

When you choose "Always Allow" on a review prompt, any other pending reviews for the same agent and scope are automatically resolved as allowed.

Scope Descriptions

Each scope in the policy editor shows a human-readable description of what that scope grants. These descriptions come from official provider documentation — for example, GitHub's repo scope shows "Grants full access to public and private repositories: code, commit statuses, invitations, collaborators, deployments, and webhooks."

The review prompt shown during a review uses a more specific endpoint-level description when available — for example, "Gets the specified message" rather than the broader scope description. This helps you make informed decisions about individual requests.

Audit Trail

Every policy decision is recorded in the proxy audit log:

  • allow — The request was auto-approved by policy.
  • approved_by_user — The request was in review and the user approved it.
  • denied_by_user — The request was in review and the user denied it.
  • block — The request was blocked by policy without prompting.
  • review_timeout — The request was in review but the user did not respond within 5 minutes.

You can review these entries in the Audit Logging interface.

Related