---
title: "Issue a signed mandate"
method: POST
path: "/v1/mandates"
---

# Issue a signed mandate

`POST /v1/mandates`

## Request

- Base URL: `https://agentmandate-api.com`
- URL: `https://agentmandate-api.com/v1/mandates`
- Auth: HTTP bearer

Signs a grant of authority to an agent and returns the mandate with a detached HMAC-SHA256 signature over its canonical bytes. The document is self-contained — store it wherever you like and present it on every verification. The signing key is per-account and never leaves the service, so a mandate signed for one account cannot verify under another.

## Request body

- object
  - `principal` string, required: Who granted the authority — the user or org the agent acts for.
  - `agent` string, required: Who holds it. A verification for a different agent is denied.
  - `notBefore` string, date-time: Defaults to now.
  - `expiresAt` string, date-time, required: Required. A mandate without an end is not a mandate.
  - `grants` object[], required
    - `action` string, required: Dotted action name. A single trailing ".*" matches one further segment — "payments.*" covers "payments.transfer" but not "payments.transfer.bulk".
    - `resources` string[]: Resource patterns, matched the same way. Omit to place no resource constraint; an empty array is rejected rather than silently granting none.
    - `maxAmountMinor` integer: Hard per-action cap, integer minor units (cents).
    - `approvalRequiredAboveMinor` integer: Above this, the action returns requires_approval unless a valid approvalToken is supplied.
    - `maxCount` integer: How many times this action may be taken under this mandate.
  - `totalSpendCapMinor` integer: Ceiling across every action, integer minor units.
  - `currency` string: ISO-4217. Required whenever any monetary cap is set.
  - `metadata` object: Carried into the receipt, never interpreted.

## Response `201`

Success

- object
  - `mandate` object
  - `signature` string: v1:<hex>. Detached — keep it with the mandate.

## Other responses

- `400`: Deterministic error. Branch on `code`; quote `requestId` when reporting a problem.
- `401`: Deterministic error. Branch on `code`; quote `requestId` when reporting a problem.
- `429`: Deterministic error. Branch on `code`; quote `requestId` when reporting a problem.
- `500`: Deterministic error. Branch on `code`; quote `requestId` when reporting a problem.

---

[API](https://skmtc.dev/agentmandate-api/apis/agent-mandate.md) · [All operations](https://skmtc.dev/agentmandate-api/apis/agent-mandate/llms.txt) · [OpenAPI document](https://skmtc.dev/agentmandate-api/apis/agent-mandate/revisions/463fe122c4d8?raw)