Agent Mandate API

Request a free sandbox API key (sends a verification email)

Starts self-serve key issuance. A one-time claim token is emailed to the address you supply; POST it to /v1/keys/claim to receive the key. No key is returned here, and the response is the same whether or not that address already has an account — so this endpoint cannot be used to find out who has one. The email is verified because your account, your usage and your invoice are all keyed to it: issuing on an unverified address would let anyone mint a working key on your account and spend your allowance. Keep using the same address and a paid plan bought with it raises the keys you already hold rather than issuing new ones.

Request body

Example request

{
  "email": "you@example.com",
  "name": "staging"
}

curl

curl -X POST https://agentmandate-api.com/v1/keys \
  -H 'content-type: application/json' \
  -d '{"email":"you@example.com","name":"staging"}'

Response

List your API keys for this API

Every key on YOUR account for this API — label, non-secret prefix, status, when it was created, when it was last used, and what it has consumed this period. Authenticate with any active key on the account; the account is taken from that key, never from a parameter, so this can only ever return your own keys. Keys you hold for other APIs in the portfolio are not listed here. Secrets are not returned and cannot be: only a peppered hash is stored. Free, and consumes no quota.

curl

curl -X GET https://agentmandate-api.com/v1/keys \
  -H "Authorization: Bearer $KEY"

Response

Issue a signed mandate

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

Example request

{
  "principal": "user_8814",
  "agent": "agent_procurement_v3",
  "expiresAt": "2026-12-31T23:59:59Z",
  "currency": "USD",
  "totalSpendCapMinor": 500000,
  "grants": [
    {
      "action": "payments.transfer",
      "resources": [
        "vendor.acme",
        "vendor.globex"
      ],
      "maxAmountMinor": 100000,
      "approvalRequiredAboveMinor": 25000
    },
    {
      "action": "invoices.*",
      "maxCount": 50
    }
  ]
}

curl

curl -X POST https://agentmandate-api.com/v1/mandates \
  -H "Authorization: Bearer $KEY" \
  -H 'content-type: application/json' \
  -d '{"principal":"user_8814","agent":"agent_procurement_v3","expiresAt":"2026-12-31T23:59:59Z","currency":"USD","totalSpendCapMinor":500000,"grants":[{"action":"payments.transfer","resources":["vendor.acme","vendor.globex"],"maxAmountMinor":100000,"approvalRequiredAboveMinor":25000},{"action":"invoices.*","maxCount":50}]}'

Response

Verify proposed actions against a mandate

Deny-by-default: an action matching no grant is denied. Returns a receipt per action with the decision, the grant that decided it, every violation (not just the first) and a digest that pins the evaluation. Send one "action" or up to 500 in "actions" — billing is one unit per action verified.

Request body

Example request

{
  "mandate": {
    "mandate": {
      "id": "mnd_…",
      "principal": "user_8814",
      "agent": "agent_procurement_v3",
      "notBefore": "2026-08-31T00:00:00Z",
      "expiresAt": "2026-12-31T23:59:59Z",
      "currency": "USD",
      "totalSpendCapMinor": 500000,
      "grants": [
        {
          "action": "payments.transfer",
          "resources": [
            "vendor.acme",
            "vendor.globex"
          ],
          "maxAmountMinor": 100000,
          "approvalRequiredAboveMinor": 25000
        },
        {
          "action": "invoices.*",
          "maxCount": 50
        }
      ]
    },
    "signature": "v1:…"
  },
  "action": {
    "agent": "agent_procurement_v3",
    "action": "payments.transfer",
    "resource": "vendor.acme",
    "amountMinor": 30000,
    "currency": "USD",
    "priorSpendMinor": 120000
  }
}

curl

curl -X POST https://agentmandate-api.com/v1/verify \
  -H "Authorization: Bearer $KEY" \
  -H 'content-type: application/json' \
  -d '{"mandate":{"mandate":{"id":"mnd_…","principal":"user_8814","agent":"agent_procurement_v3","notBefore":"2026-08-31T00:00:00Z","expiresAt":"2026-12-31T23:59:59Z","currency":"USD","totalSpendCapMinor":500000,"grants":[{"action":"payments.transfer","resources":["vendor.acme","vendor.globex"],"maxAmountMinor":100000,"approvalRequiredAboveMinor":25000},{"action":"invoices.*","maxCount":50}]},"signature":"v1:…"},"action":{"agent":"agent_procurement_v3","action":"payments.transfer","resource":"vendor.acme","amountMinor":30000,"currency":"USD","priorSpendMinor":120000}}'

Response

Revoke a mandate

Adds the mandate to your account's revocation list. Idempotent — revoking twice is not an error. Verifications read a briefly cached copy of that list so they never block on the database, so a revocation takes effect within about ten seconds rather than instantly. That window is stated here rather than hidden.

Request body

Example request

{
  "reason": "agent decommissioned"
}

curl

curl -X POST https://agentmandate-api.com/v1/mandates/{id}/revoke \
  -H "Authorization: Bearer $KEY" \
  -H 'content-type: application/json' \
  -d '{"reason":"agent decommissioned"}'

Response

List the mandates you have revoked

Account-scoped. Useful for reconciling your own records against the list verifications actually consult.

curl

curl -X GET https://agentmandate-api.com/v1/revocations \
  -H "Authorization: Bearer $KEY"

Response

Public demo — issue and verify in one call, without a key

Signs the mandate you describe with a throwaway demo key, then verifies your actions against it. The real engine, capped at 10 actions. Nothing is stored, nothing is metered, and the demo signature is not usable on the authenticated endpoint.

Request body

Example request

{
  "mandate": {
    "principal": "user_8814",
    "agent": "agent_procurement_v3",
    "expiresAt": "2026-12-31T23:59:59Z",
    "currency": "USD",
    "totalSpendCapMinor": 500000,
    "grants": [
      {
        "action": "payments.transfer",
        "resources": [
          "vendor.acme",
          "vendor.globex"
        ],
        "maxAmountMinor": 100000,
        "approvalRequiredAboveMinor": 25000
      },
      {
        "action": "invoices.*",
        "maxCount": 50
      }
    ]
  },
  "action": {
    "action": "payments.transfer",
    "resource": "vendor.acme",
    "amountMinor": 30000,
    "currency": "USD"
  }
}

curl

curl -X POST https://agentmandate-api.com/v1/demo/verify \
  -H 'content-type: application/json' \
  -d '{"mandate":{"principal":"user_8814","agent":"agent_procurement_v3","expiresAt":"2026-12-31T23:59:59Z","currency":"USD","totalSpendCapMinor":500000,"grants":[{"action":"payments.transfer","resources":["vendor.acme","vendor.globex"],"maxAmountMinor":100000,"approvalRequiredAboveMinor":25000},{"action":"invoices.*","maxCount":50}]},"action":{"action":"payments.transfer","resource":"vendor.acme","amountMinor":30000,"currency":"USD"}}'

Response

Every violation code the engine can return

Branch on these rather than on the human-readable detail, which may change.

curl

curl -X GET https://agentmandate-api.com/v1/violations

Response

Start a hosted Square checkout for a paid tier

Returns a Square-hosted payment URL for the requested tier. No API key is needed — a prospect has not got one yet. The email Square collects becomes the account, so a key issued later for the same address inherits the paid quota. Enterprise returns a contact route rather than a payment link.

Request body

Example request

{
  "tier": "developer"
}

curl

curl -X POST https://agentmandate-api.com/v1/checkout \
  -H 'content-type: application/json' \
  -d '{"tier":"developer"}'

Response

Every invoice issued against this account, newest first (dashboard session required)

Returns the stored `api_plan_invoices` rows for this account and this API — the rows the billing run actually wrote, never a reconstruction. Each one reconciles against itself: the included allowance and base fee shown are the PRORATED figures applied to that window, `overageMinorRaw` is the uncapped overage and `overageMinorCapped` is what was charged, and `baseChargedMinor` says how much of the base fee this invoice collected — 0 when Square’s recurring subscription had already taken it. An account with no billing history yet gets an empty list and a `note` explaining why, never a fabricated row. AUTHENTICATION IS YOUR DASHBOARD SESSION, NOT AN API KEY. Send the `@sp/core` session cookie this API sets when you sign in, from the same origin. An API key is refused here on purpose: it is a data-plane credential that lives in CI and in third-party integrations, and it must never be able to change what you are billed, cancel your account, or read your payment history. Errors: 401 `unauthenticated` when there is no valid session, 403 `forbidden` when the request is cross-origin or its `x-csrf-token` header is missing or wrong.

curl

curl -X GET https://agentmandate-api.com/v1/invoices

Response

Revoke one of your API keys

Kills a key immediately: the very next request made with it is refused with 401 invalid_api_key. There is no propagation delay and no cache to wait out. You may revoke the key you are authenticating with — that is the correct move when it has leaked, though you will then need another key, or the email flow, to get back in; rotate does both in one call. A key belonging to another account, or to another API, answers 404 exactly as an unknown id does, so this cannot be used to probe for keys you do not own. Idempotent, and free.

curl

curl -X POST https://agentmandate-api.com/v1/keys/{id}/revoke \
  -H "Authorization: Bearer $KEY"

Response

Replace one of your API keys with a new secret

Issues a replacement key and revokes the old one. This is the answer to a leaked or lost key: the new secret is returned once, the old secret stops working immediately, and the label carries over unless you supply a new one. The replacement is issued at your account's current allowance — your paid plan if you have one — not at the old key's. Rotating does not count against the active-key limit, because it replaces rather than adds. Free, and it works while you are out of quota.

Request body

Example request

{
  "name": "production (rotated)"
}

curl

curl -X POST https://agentmandate-api.com/v1/keys/{id}/rotate \
  -H "Authorization: Bearer $KEY" \
  -H 'content-type: application/json' \
  -d '{"name":"production (rotated)"}'

Response

Exchange an emailed claim token for the API key

Spends the token emailed by POST /v1/keys and returns the key. The key is shown ONCE — only a peppered hash is stored, so it can never be read back; if you lose it, rotate. The key works only on this API, and the allowance it is issued with reflects your account: your paid plan when you have one, the free sandbox allowance when you do not.

Request body

Example request

{
  "token": "eyJ2IjoxLCJlIjoieW91QGV4YW1wbGUuY29tIn0.ZXhhbXBsZQ"
}

curl

curl -X POST https://agentmandate-api.com/v1/keys/claim \
  -H 'content-type: application/json' \
  -d '{"token":"eyJ2IjoxLCJlIjoieW91QGV4YW1wbGUuY29tIn0.ZXhhbXBsZQ"}'

Response

Every payment attempted against this account and how it went (dashboard session required)

The money movements behind your invoices, newest first: what was charged, whether it succeeded, and the processor’s payment id when it did. A billing period that came to nothing produces NO row here — it was closed without asking the processor for anything, and listing it would show you a payment that never happened. A failed attempt does appear, with its reason, because that is why an account goes past due. AUTHENTICATION IS YOUR DASHBOARD SESSION, NOT AN API KEY. Send the `@sp/core` session cookie this API sets when you sign in, from the same origin. An API key is refused here on purpose: it is a data-plane credential that lives in CI and in third-party integrations, and it must never be able to change what you are billed, cancel your account, or read your payment history. Errors: 401 `unauthenticated` when there is no valid session, 403 `forbidden` when the request is cross-origin or its `x-csrf-token` header is missing or wrong.

curl

curl -X GET https://agentmandate-api.com/v1/payments

Response

Your current plan, billing window and available changes (dashboard session required)

Reports the plan this account is on, the billing window it is in, any tier change already staged for the next invoice, and the full pricing ladder marked up so you can see which rungs are an upgrade and which a downgrade. `planChangesGoThrough` is the field to branch on: `self_serve` means POST /v1/subscription/plan can move you; `checkout` means Square’s own recurring subscription holds your price and the tier has to move with it. All money is in integer minor units (cents). AUTHENTICATION IS YOUR DASHBOARD SESSION, NOT AN API KEY. Send the `@sp/core` session cookie this API sets when you sign in, from the same origin. An API key is refused here on purpose: it is a data-plane credential that lives in CI and in third-party integrations, and it must never be able to change what you are billed, cancel your account, or read your payment history. Errors: 401 `unauthenticated` when there is no valid session, 403 `forbidden` when the request is cross-origin or its `x-csrf-token` header is missing or wrong.

curl

curl -X GET https://agentmandate-api.com/v1/subscription

Response

Cancel this plan and end metered access (dashboard session required)

Cancels the plan and drops every API key on this account for this product to a ceiling of 0, so access ends at the moment you cancel rather than at some later date nothing would enforce. The open billing window is never invoiced, so on a plan we bill directly the charging stops at the same instant the access does. When Square’s own recurring subscription collects your flat monthly fee (`baseFeeOwner` is `provider`) this API cannot stop that charge, so the request is refused with 409 unless you send `acknowledgeProviderBilling: true` — that flag exists so nobody ends up with a ceiling of zero and a live monthly charge without having been told first. AUTHENTICATION IS YOUR DASHBOARD SESSION, NOT AN API KEY. Send the `@sp/core` session cookie this API sets when you sign in, from the same origin. An API key is refused here on purpose: it is a data-plane credential that lives in CI and in third-party integrations, and it must never be able to change what you are billed, cancel your account, or read your payment history. Errors: 401 `unauthenticated` when there is no valid session, 403 `forbidden` when the request is cross-origin or its `x-csrf-token` header is missing or wrong.

Request body

Example request

{
  "acknowledgeProviderBilling": true
}

curl

curl -X POST https://agentmandate-api.com/v1/subscription/cancel \
  -H 'content-type: application/json' \
  -d '{"acknowledgeProviderBilling":true}'

Response

Upgrade or downgrade to another plan (dashboard session required)

Moves this account to another rung of the published pricing ladder and re-derives the ceiling enforced against every API key on it, so an upgrade is usable immediately rather than at the next invoice. The change is STAGED, not overwritten: the current billing window is closed at this instant and priced against the tier that was actually in force for it, and the incoming tier opens the next window with the original billing anniversary preserved. A downgrade therefore never re-prices days you already consumed on the dearer plan. Refused with 409 when Square’s own recurring subscription holds your price (`baseFeeOwner` is `provider`) — read `planChangesGoThrough` from GET /v1/subscription first; that case changes tier and price together through checkout. AUTHENTICATION IS YOUR DASHBOARD SESSION, NOT AN API KEY. Send the `@sp/core` session cookie this API sets when you sign in, from the same origin. An API key is refused here on purpose: it is a data-plane credential that lives in CI and in third-party integrations, and it must never be able to change what you are billed, cancel your account, or read your payment history. Errors: 401 `unauthenticated` when there is no valid session, 403 `forbidden` when the request is cross-origin or its `x-csrf-token` header is missing or wrong.

Request body

Example request

{
  "planId": "growth"
}

curl

curl -X POST https://agentmandate-api.com/v1/subscription/plan \
  -H 'content-type: application/json' \
  -d '{"planId":"growth"}'

Response

Your consumption and remaining allowance for this period

Reports what this API key has consumed in the current quota period, the ceiling being enforced against it, and when that ceiling resets. Free, and it consumes no quota, so it still answers once you are getting 429 quota_exceeded — which is the point: compare "used" against "ceiling" and read "period.resetsAt" to tell a period you have simply exhausted from a plan that is no longer active, which shows as a "status" of canceled and a ceiling of 0. "used" counts billing units (see "unit"), not HTTP requests: a single request can consume several. All money is in integer minor units (cents), never a decimal. The period reported here is the quota period — the calendar month in UTC, resetting at 00:00 UTC on the 1st. Your invoice window is anchored to the date you subscribed and is a different window; the amounts here are what this period’s usage has accrued so far, not a bill.

curl

curl -X GET https://agentmandate-api.com/v1/usage \
  -H "Authorization: Bearer $KEY"

Response

Service index — endpoints, auth and error format

curl

curl -X GET https://agentmandate-api.com/

Response

Liveness and deployed version

curl

curl -X GET https://agentmandate-api.com/health

Response