Manage platform scopes

A scope is the granular unit of what an agent may do on a platform. Each scope maps a name to one or more (HTTP method, endpoint pattern) pairs. When an agent makes a call, the proxy checks the actual method + endpoint against the granted scope’s patterns before it decrypts any credential — so a read-only scope can never be used to delete, even if the agent asks.

Scopes come in two kinds:

• Curated — shipped by AgentValet for well-known platforms (e.g. Metabase). Read-only here; you can’t edit or delete them.
• Custom — defined by your org’s admins, for any platform including internal APIs we don’t ship a connector for. Visible and editable only within your org.

Open the scope manager

From a policy: open Policies → New policy (or any policy), then click Manage scopes in the Rules header. The modal lists every scope for each platform with a curated / custom badge, its method, and its endpoint pattern.

Add a custom scope

In Add a custom scope, fill:

• Platform — the connected platform (or any platform id).
• Scope id — the exact id the agent will present, e.g. metabase:report.run. This must match what the agent sends as its scope and what you grant in the permission matrix.
• Method — GET / POST / PUT / PATCH / DELETE, or ANY to match every method.
• Endpoint pattern — the API path, starting with /. Wildcards:
  • * matches exactly one path segment — /api/report/* matches /api/report/42 but not /api/report/42/runs.
  • ** matches the rest of the path — /api/report/** matches /api/report/42/runs.
  • Query strings are ignored when matching.

Add several patterns under the same scope id to cover multiple endpoints (for example a CSV and an XLSX export both under one export scope). A call is allowed if any pattern for the granted scope matches.

How it shows up

Once defined, a custom scope appears in the policy rule scope dropdown and in the agent permission grid alongside curated scopes, so you can allow, deny, require approval, or tag it like any other scope.

What happens at call time

Related guides

• Manage user policies
• Manage org guardrails
• Configure an agent’s permissions