> ## Documentation Index
> Fetch the complete documentation index at: https://docs.inviolet.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API

> Hit Inviolet's HTTP API directly — mint mandates and guard tool calls from any language.

Every SDK is a thin wrapper over these HTTP endpoints. Use them directly from
any language, or when you want fine-grained control. The full endpoint reference
lives under [API Reference](/api-reference/http-api).

## Authentication

```http theme={"dark"}
Authorization: Bearer <INVIOLET_API_KEY>
```

## 1. Mint a mandate

Validates the requested scope against the intent card, then returns a signed,
short-lived [mandate](/concepts/mandates) JWT.

```http theme={"dark"}
POST /v1/mandate/dispense
Content-Type: application/json

{
  "actor": "alice@example.com",
  "intent_id": "intents:customer_support_lookup",
  "requested_scope": {
    "operations": ["postgres.select"],
    "resources": ["contacts.first_name", "contacts.last_name"]
  },
  "audience": "postgres-prod"
}
```

### Response

```json theme={"dark"}
{
  "credential": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "cred_id": "b1e7...",
  "expires_at": "2026-07-20T12:30:00Z",
  "ttl_seconds": 300,
  "broker_dispense": null
}
```

If the requested scope exceeds the intent card, the gateway returns `403` with
`code: "mandate_violation"` and a `suggested_narrower_scope`. See
[POST /v1/mandate/dispense](/api-reference/dispense) for every field.

## 2. Guard a tool call

Attach the mandate as `X-Inviolet-Mandate` and post the action to the decision
engine.

```http theme={"dark"}
POST /v1/mcp-proxy/call
Content-Type: application/json
X-Inviolet-Mandate: eyJhbGciOiJSUzI1NiI...

{
  "action": {
    "surface": "sdk",
    "operation": "postgres.select",
    "arguments": { "table": "contacts", "id": 42 }
  },
  "audience": "postgres-prod"
}
```

The response `kind` starts with `allow` when the call may proceed. Other kinds
map to actions: `approval` (queued for a human — poll status), `step_up` (run
the IdP challenge and retry), `deny_with_reroute` (fall back to the rerouted
handler), or a hard `deny`. See [POST /v1/mcp-proxy/call](/api-reference/decide)
for the full list of decision kinds and status codes.

## 3. Verify a mandate

The gateway publishes its public keys as a JWKS document. Verify the RS256
signature locally with any JWT library.

```http theme={"dark"}
GET /v1/mandate/jwks
```

See [GET /v1/mandate/jwks](/api-reference/jwks).

## Revoke a mandate

```http theme={"dark"}
POST /v1/mandate/revoke
Content-Type: application/json

{ "cred_id": "b1e7...", "reason": "session ended" }
```

Adds the `cred_id` to the blocklist and propagates to any downstream credential
broker.

## Full OpenAPI spec

The complete OpenAPI spec powers the [API Reference](/api-reference/http-api)
tab — use it to auto-generate clients in any language.

## Read next

* **[API Reference](/api-reference/http-api)** — every endpoint in detail
* **[Node SDK](/sdks/node)** — the typed client for JavaScript / TypeScript
* **[Python](/sdks/python)** — the same REST flow from Python