---
title: "Authorize acquiring or exercising a capability"
method: POST
path: "/authorize/capability"
---

# Authorize acquiring or exercising a capability

`POST /authorize/capability`

## Request

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

CAP-1: installing a skill, adding a plugin, calling a new API — new capability is a governed action. Evaluated against the wallet's ordered capability rules (namespaced prefix-glob patterns like skill:install:*, effect block/allow/escalate; empty = allow all). Escalations persist to the approval inbox with replayable evidence; approval mints a one-use grant — retry with grant_id to consume. Supports Idempotency-Key.

## Request body

- object
  - `capability` string, required: Namespaced capability id, e.g. skill:install:web-scraper, plugin:browser, api:github.com/repos
  - `arguments` object: Advisory — not policy-evaluated or persisted
  - `grant_id` string: One-use grant from an approval; retry the same capability with this to consume it

## Response `200`

allowed or escalated (poll /authorize/{id}, or replay the Idempotency-Key for status — an approved escalation replays authorized: false with approval_status; redeem the grant)

## Other responses

- `401`: Invalid API key
- `403`: Denied by policy or grant mismatch
- `409`: Grant already consumed

---

[API](https://skmtc.dev/getsanction/apis/sanction-agent-governance-api.md) · [All operations](https://skmtc.dev/getsanction/apis/sanction-agent-governance-api/llms.txt) · [OpenAPI document](https://skmtc.dev/getsanction/apis/sanction-agent-governance-api/revisions/c645a9e4b72d?raw)