Authorize a tool invocation

Check whether an agent may invoke a tool or external action (an MCP tool, a shell command, a deploy). Governed by the wallet's tool block/allow/escalate lists; an empty allow-list allows all (governance is opt-in). Escalated invocations persist to the owner's approval inbox; approval mints a one-use grant — retry the same tool with grant_id to consume it, or poll /authorize/{id}. Supports Idempotency-Key: replaying the key returns the escalation's current state, including the terminal decision once resolved.

post/authorize/tool

Request

  • Base URL: https://getsanction.com/api/v1
  • URL: https://getsanction.com/api/v1/authorize/tool
  • Auth: API key in header x-api-key

Request body

toolstring required

Exact name of the tool/action about to be invoked (e.g. github.create_deployment, shell.exec)

serverstring

MCP server or integration the tool belongs to (e.g. github, filesystem) — matched on grant redemption

argumentsobject

Arguments bound to a one-use approval. Encrypted at rest; reviewed by an admin in the dashboard. Not policy-evaluated. Maximum request size 64 KiB and nesting depth 32.

inputobject

Legacy SDK alias for arguments. Send only one of input or arguments.

require_approvalboolean

Request a one-off human approval even when policy allows. Enforced in observe mode; hard denials win. Timeout always denies.

approval_reasonstring

Why the agent requests review. Shown to the owner; omit secrets.

grant_idstring

One-use grant minted when a human approves the escalation. Retry the same tool, server, and arguments with this field to consume it. Legacy unbound tool grants require fresh approval.

Response

Authorization decision (200 for allowed/escalated; 403 for denied; 409 for an already-consumed grant)

authorizedboolean
approval_statusstring

Historical status on an idempotent replay; never permission to execute. Redeem the grant for an attempt.

status'allowed' | 'denied' | 'escalated'
request_idstring

Decision request ID. A consumed tool-grant replay gets a separate denied attempt ID; poll /authorize/{id} for its terminal decision.

original_request_idstring

Original approval request linked to a consumed tool-grant replay, after wallet and agent ownership checks.

rejected_grant_idstring

Consumed grant referenced for audit only. Never usable authority.

reasonstring
code'TOOL_BLOCKED' | 'TOOL_NOT_ALLOWED' | 'TOOL_ESCALATION_REQUIRED' | 'NO_POLICY' | 'GRANT_NOT_FOUND' | 'GRANT_ALREADY_USED' | 'GRANT_EXPIRED' | 'GRANT_MISMATCH' | 'GRANT_UNSUPPORTED'

Machine-readable decision code (absent when allowed)

remediationstring

Hint for how the agent should proceed

agentstring
toolstring
serverstring
grant_idstring

Echoed on successful grant redemption

grant_status'consumed'
grant_consumed_atstring date-time

Changes

No recorded changes to this operation across all 1 revision of this API.