Authorize a spend action

Check whether an agent is permitted to make a purchase, subscription, or transfer. Always call this before any financial transaction. Returns immediately with approved, denied, or escalated status. Escalated means a human must approve before proceeding; after approval, retry the exact request with grant_id to consume the one-use grant.

post/authorize

Request

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

Request body

action'purchase' | 'subscribe' | 'transfer' required

Type of spend action the agent wants to perform

amount_usdnumber required

Amount in US dollars

merchantstring required

Vendor or service name

categorystring required

Spend category (e.g. software, services, research, infrastructure)

descriptionstring

Optional description of what this spend is for

tagsobject

Optional attribution tags (≤8; e.g. {"channel":"paid-media","play":"d2c-search"}). Stored on the decision and surfaced in the audit feed/CSV for rollups. Never read by policy rules.

grant_idstring

Short-lived approval grant returned from GET /authorize/{request_id}. Retry the exact approved request with this field to consume the grant.

Response

Authorization decision (200 for approved/escalated; 403 for denied)

authorizedboolean
approval_statusstring

Present when an idempotent replay hits an escalation that a human (or timeout-approve) approved: status only, never permission to execute. Redeem the one-use grant for an attempt. Policy-approved requests replay authorized: true.

status'approved' | 'denied' | 'escalated' | 'pending'
reasonstring

Human-readable explanation of the decision

code'ESCALATION_REQUIRED' | 'ESCALATION_TIMED_OUT' | 'NO_POLICY' | 'CATEGORY_BLOCKED' | 'CATEGORY_NOT_ALLOWED' | 'PER_TXN_LIMIT' | 'DAILY_BUDGET_EXCEEDED' | 'MONTHLY_BUDGET_EXCEEDED' | 'SUBTREE_CAP_EXCEEDED' | 'EXEC_BUDGET_EXCEEDED' | 'GRANT_NOT_FOUND' | 'GRANT_ALREADY_USED' | 'GRANT_EXPIRED' | 'GRANT_MISMATCH' | 'GRANT_UNSUPPORTED' | 'POLICY_DENIED'

Stable machine-readable decision code (absent when approved). Branch on this to replan.

remediationstring

Suggested next step for the agent when not approved

request_idstring
agentstring
amount_usdnumber
merchantstring
grant_idstring

Grant issued by a human approval for this request

grant_status'active' | 'consumed' | 'expired' | 'revoked'
grant_consumed_atstring date-time
grant_expires_atstring date-time

Changes

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