Scope grants

By default, an agent token (agent_* or sess_*) is single-agent-scoped — the agent can only act on its own resources. Reading sibling agents, mutating their state, or moving funds between agents requires an explicit, audited capability grant issued by a tenant owner. This is the same model as Unix sudo: low-friction baseline, traceable elevation, no global admin keys floating around in agent configs.

The three scope tiers

tenant_read

Read any sibling agent — wallets, balances, transfers, audit. Standing grants capped at 60 minutes.

tenant_write

Mutate sibling agent state — policies, skills, status, freeze. Standing grants capped at 15 minutes.

treasury

Move funds — settlement on x402/pay, acp/checkouts/:id/complete, ap2/mandates/:id/execute, ucp/checkouts/:id/complete, and sibling send-usdc. One_shot only (DB-enforced).

The default agent tier is implicit — every agent token already has it. You only request elevation when you hit a 403 SCOPE_REQUIRED.

Lifecycle

agent calls request_scope     →   scope_requested  audit row (pending)
tenant owner approves         →   scope_granted    audit row + grant row (active)
agent calls gated route       →   scope_used       audit row + grant (consumed if one_shot)
tenant owner revokes          →   scope_revoked    audit row + grant (revoked)
expires_at passes             →   scope_expired    audit row + grant (expired)
24h elapsed (standing only)   →   scope_heartbeat  audit row (long-lived grant reminder)

Every transition writes a row to auth_scope_audit with the actor, route, and environment. Audit rows persist past agent deletion — you always have a complete trail.

For the calling agent

Detect that you need a scope

Hit any privileged endpoint with default scope and you’ll get:

{
  "error": "Scope 'tenant_read' required; caller has 'agent'. Call request_scope({ scope: 'tenant_read', purpose: '...' }) and have the tenant owner approve, or have them issue a standing grant from the dashboard.",
  "code": "SCOPE_REQUIRED",
  "required_scope": "tenant_read",
  "current_scope": "agent",
  "hint": "Call request_scope(...)"
}

Request elevation

curl -X POST https://api.getsly.ai/v1/auth/scopes/request \
  -H "Authorization: Bearer agent_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "tenant_read",
    "lifecycle": "one_shot",
    "purpose": "Read sibling agent Tina-2 wallet to plan a fund split"
  }'

// @sly_ai/mcp-server@0.5.0+ exposes request_scope
await tools.request_scope({
  scope: "tenant_read",
  lifecycle: "one_shot",
  purpose: "Read sibling agent Tina-2 wallet to plan a fund split"
});
// → { request_id: "uuid", status: "pending" }

Response (202):

{
  "data": {
    "request_id": "uuid",
    "status": "pending",
    "message": "Scope request submitted. A tenant owner must approve it via the dashboard before the elevation takes effect."
  }
}

Poll for the decision

curl https://api.getsly.ai/v1/auth/scopes/<request_id> \
  -H "Authorization: Bearer agent_YOUR_TOKEN"

await tools.scope_status({ requestId: "<request_id>" });
// → { status: "pending" | "approved" | "denied", grant?, denial_reason? }

Possible terminal states:

`status`	What to do
`pending`	Wait. Operator hasn’t decided yet. Polling once every 5–15s is fine.
`approved`	Retry the privileged call. The grant is live.
`denied`	Surface `denial_reason` to your model. Don’t retry the same scope without a new ask.

Inspect current scope

curl https://api.getsly.ai/v1/auth/scopes/active \
  -H "Authorization: Bearer agent_YOUR_TOKEN"

await tools.scope_status();
// → { current_scope: "agent" | "tenant_read" | ..., grants: [...] }

Returns current_scope (your effective tier right now) and the active grants applicable to the current call.

Lifecycle gotchas

one_shot is one shot. First successful gated call consumes the grant. Subsequent calls 403 until you request again.

Concurrency-safe. Gated routes await recordScopeUse before responding, so two parallel calls can’t share one one_shot — exactly one wins.

No cache lag. The auth middleware re-queries auth_scope_grants on every request, so revoke and consumption reflect immediately.

For tenant owners

Approve / deny via the dashboard

Open /dashboard/security/scopes (Settings → Scope Grants). Pending requests appear at the top with the agent name, requested scope, lifecycle, purpose, and timestamp.

tenant_read approves with a single click.
tenant_write and treasury open a typed-confirmation modal — you must type the agent’s name to enable the green button. Per-scope risk callouts (move funds, mutate sibling agent state) make the blast radius explicit.
Deny prompts for a reason. The reason surfaces back to the agent’s scope_status poll.

Below pending: every active grant in the tenant with a Revoke button. Below that: a filtered audit feed with action chips, agent picker, and free-text search.

Issue a standing grant directly

Click + Issue grant on the Active grants section. Pick agent, scope, lifecycle, duration, and purpose. Treasury auto-locks lifecycle to one_shot.

Per-agent view

/dashboard/agents/[id] has a Scopes tab showing just that agent’s grants + audit history. Useful for ops review of a single agent.

API path for server-to-server automation

Tenant API keys (pk_*) carry full owner-equivalent privilege and can drive the lifecycle without a JWT login.

# Issue a standing grant
curl -X POST https://api.getsly.ai/v1/organization/scopes \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "...",
    "scope": "tenant_read",
    "lifecycle": "standing",
    "duration_minutes": 30,
    "purpose": "..."
  }'

# Decide a pending request
curl -X POST https://api.getsly.ai/v1/organization/scopes/<requestId>/decide \
  -H "Authorization: Bearer pk_live_..." \
  -d '{ "decision": "approve" }'   # or { "decision": "deny", "reason": "..." }

# Revoke
curl -X DELETE https://api.getsly.ai/v1/organization/scopes/<grantId> \
  -H "Authorization: Bearer pk_live_..."

# List active grants (defaults to current env; ?env=all spans both)
curl https://api.getsly.ai/v1/organization/scopes \
  -H "Authorization: Bearer pk_live_..."

# Audit feed (filters: ?agent_id=... ?env=all ?limit=200)
curl https://api.getsly.ai/v1/organization/scopes/audit \
  -H "Authorization: Bearer pk_live_..."

When issuing via API key, granted_by_user_id is auto-resolved to the tenant’s primary owner so the “every elevation has a real human approver” invariant holds. The audit row records actor_type='api_key' + granted_via_api_key: true for traceability.

Auto-cascading revokes

Two operator actions wipe every active grant for an agent:

Action	Cascade
Kill switch (`/v1/agents/:id/kill-switch`)	Suspends the agent + revokes all active grants. Response includes `scopeGrantsRevoked: N`.
Wallet freeze (`/v1/agents/:agentId/wallet/freeze`)	Locks the wallet + revokes all active grants.

Audit rows for cascaded revokes carry request_summary.reason: "kill_switch_cascade" so the trail distinguishes operator-driven revokes from manual ones.

Environment scoping

auth_scope_grants and auth_scope_audit carry an environment column populated from the target agent’s env (not the issuer’s). All read endpoints default to caller-env scoping; pass ?env=all to opt out (intended for cross-env tooling, not the dashboard). A live-env dashboard never shows test-env scope events and vice versa. Issuing a grant via a tenant API key with X-Environment: live for a test-env agent still tags the grant test — env follows the agent.

Currently gated routes

Method	Path	Required scope
GET	`/v1/agents/:id`	`tenant_read` (sibling)
PATCH	`/v1/agents/:id`	`tenant_write` (sibling)
POST	`/v1/agents/:agentId/wallet/freeze`	`tenant_write` (sibling)
POST	`/v1/agents/:agentId/wallet/unfreeze`	`tenant_write` (sibling)
PUT	`/v1/agents/:agentId/wallet/policy`	`tenant_write` (sibling)
POST	`/v1/agents/:id/smart-wallet/send-usdc`	`treasury` (sibling)
POST	`/v1/x402/pay`	`treasury`
POST	`/v1/acp/checkouts/:id/complete`	`treasury`
POST	`/v1/ap2/mandates/:id/execute`	`treasury`
POST	`/v1/ucp/checkouts/:id/complete`	`treasury`

Same-agent calls (where caller’s actorId equals the target id) bypass the gate. Tenant API keys + JWT users are unaffected — their existing tenant-wide auth is preserved.

Failure-mode debugging

`SCOPE_REQUIRED` 403 when I expect to have permission

Hit GET /v1/auth/scopes/active. If current_scope is agent but you expected an elevation:

Grant might be consumed (one_shot used) or expired
parent_session_id might not match your current session — session-anchored grants only apply to the originating sess_*
Env mismatch — agent is test, calling endpoint with X-Environment: live

Approve button doesn't appear / dashboard empty

The logged-in user might be on a different tenant than the requesting agent. JWT auth derives tenant from user_profiles.tenant_id. The audit endpoint also defaults to env-scoping — switch dashboard env or use ?env=all.

Stuck-cache after revoke

Should not happen — every request re-queries scope. If you see this, file a regression.

Agent tokens — the agent_* bearer credential
Ed25519 sessions — sess_* per-session tokens
Kill-switch — break-glass with cascade
Wallet policies — same-agent spending caps (lower tier than treasury scope)

Get Started

Onboarding

Migration

Authentication

Core Concepts

Guides

Recipes

Architecture

Settlement & Treasury

Stellar

Protocols

Agent Platform

SDKs & Tools

Webhooks

Resources

Scope grants

The three scope tiers

tenant_read

tenant_write

treasury

Lifecycle

For the calling agent

Detect that you need a scope

Request elevation

Poll for the decision

Inspect current scope

Lifecycle gotchas

For tenant owners

Approve / deny via the dashboard

Issue a standing grant directly

Per-agent view

API path for server-to-server automation

Auto-cascading revokes

Environment scoping

Currently gated routes

Failure-mode debugging

​The three scope tiers

tenant_read

tenant_write

treasury

​Lifecycle

​For the calling agent

​Detect that you need a scope

​Request elevation

​Poll for the decision

​Inspect current scope

​Lifecycle gotchas

​For tenant owners

​Approve / deny via the dashboard

​Issue a standing grant directly

​Per-agent view

​API path for server-to-server automation

​Auto-cascading revokes

​Environment scoping

​Currently gated routes

​Failure-mode debugging

​Related

The three scope tiers

Lifecycle

For the calling agent

Detect that you need a scope

Request elevation

Poll for the decision

Inspect current scope

Lifecycle gotchas

For tenant owners

Approve / deny via the dashboard

Issue a standing grant directly

Per-agent view

API path for server-to-server automation

Auto-cascading revokes

Environment scoping

Currently gated routes

Failure-mode debugging

Related