Mandates

Base URL: https://api.codespar.dev

Every operation below requires a Bearer token. See Authentication.

These five operations read and transition a consumer mandate: the allowance a consumer signed for one agent, with a purpose, a payee allowlist, per-currency caps and an expiry. None of them creates one. A mandate is born in the consent flow (POST /v1/consents, then the consumer signs at the hosted page) and is signed server-side, so there is no signing step on your side. The concept page, Mandates, receipts and approvals, has the matrix of what exists per channel (REST, SDK, CLI, dashboard, meta-tool), the lifecycle, and what is still not in this document.

The same four operations are also registered under /v1/consumers/mandates/..., the older spelling. Both spellings are described below and both work; the ones without /consumers are canonical, the others carry a deprecation mark. One handler serves each pair, so switching the path changes nothing else.

Every operation, from the spec

Generated from the published OpenAPI document, so it never drifts from what the API actually serves. The section above is written by hand and carries what a schema cannot: the object model, field rules, and the order to call things in.

GET /v1/mandates

List consumer allowances

The allowances a consumer has signed, newest first by creation time. Scoped to the credential's organization by a predicate in the SELECT, so nothing in the query can widen it.

limit caps the page at 200 and defaults to 50, and there is NO cursor: the response carries the rows and nothing to page with, so a consumer with more allowances than the limit is truncated in silence. Narrow with consumer_id and status rather than paging.

A status this filter does not know is a 400, not an empty list. That matters because an unrecognised value answering { "mandates": [] } reads as "this consumer has none" when it means "you asked for a state that does not exist".

The response object has one key, mandates, and no count.

GET /v1/consumers/mandates is the legacy spelling of this same operation, kept for two releases (ent#979): same handler, same mandates:read scope.

Query parameters

Responses

Response 200

curl -X GET https://api.codespar.dev/v1/mandates \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

GET /v1/mandates HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEY

import os
import requests

res = requests.get(
    "https://api.codespar.dev/v1/mandates",
    headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"},
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://api.codespar.dev/v1/mandates", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
  },
});

const data = await res.json();

const result = await cs.api.get("/v1/mandates");

{
  "mandates": [
    {
      "id": "obj_0000000000000000",
      "consumer_id": "csm_0000000000000000",
      "agent_id": "agt_0000000000000000",
      "display_name": "Example",
      "purpose": "string",
      "merchant_allowlist": [
        "string"
      ],
      "merchant_pin_kind": "pix-key",
      "intent_note": "string",
      "cap_minor": "1000",
      "per_tx_cap_minor": "1000",
      "currency": "BRL",
      "status": "active",
      "expires_at": "2026-01-15T12:00:00.000Z",
      "created_at": "2026-01-15T12:00:00.000Z"
    }
  ]
}

GET /v1/mandates/{id}

Read one consumer allowance

The same 14-field projection the listing returns, by id, from the same table and under the same organization predicate, plus org_paused / org_paused_at: whether the organization's kill switch is pressed (ent#1648).

This path has NO alias. Its four siblings are registered twice each, under /v1/mandates/... and /v1/consumers/mandates/...; this one is registered once, because point reads of an allowance did not exist before it and there was no older spelling to keep alive.

Path parameters

Responses

Response 200

curl -X GET https://api.codespar.dev/v1/mandates/{id} \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

GET /v1/mandates/{id} HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEY

import os
import requests

res = requests.get(
    "https://api.codespar.dev/v1/mandates/{id}",
    headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"},
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://api.codespar.dev/v1/mandates/{id}", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
  },
});

const data = await res.json();

const result = await cs.api.get("/v1/mandates/{id}", {
  path: {
    id: "mandate_0000000000000000"
  }
});

{
  "id": "obj_0000000000000000",
  "consumer_id": "csm_0000000000000000",
  "agent_id": "agt_0000000000000000",
  "display_name": "Example",
  "purpose": "string",
  "merchant_allowlist": [
    "string"
  ],
  "merchant_pin_kind": "pix-key",
  "intent_note": "string",
  "cap_minor": "1000",
  "per_tx_cap_minor": "1000",
  "currency": "BRL",
  "status": "active",
  "expires_at": "2026-01-15T12:00:00.000Z",
  "created_at": "2026-01-15T12:00:00.000Z",
  "org_paused": true,
  "org_paused_at": "2026-01-15T12:00:00.000Z",
  "periodic_cap": {
    "window": "day",
    "cap_minor": "1000"
  },
  "withdrawal_allowlist": [
    "string"
  ],
  "dda_allowlist": [
    "string"
  ],
  "slots": [
    {
      "currency": "BRL",
      "rail": "string",
      "cap_minor": "1000",
      "per_tx_cap_minor": "1000"
    }
  ],
  "funding": {
    "rail": "string",
    "currency": "BRL"
  },
  "usage": {
    "spent_minor": "1000",
    "period_spent_minor": "1000"
  }
}

POST /v1/mandates/{id}/pause

Pause an allowance

Moves an active allowance to paused. active is the only legal source: a paused, revoked or expired allowance answers 409 rather than being quietly re-paused, and an allowance that is already paused answers 200 with changed: false and writes nothing.

Pausing stops the spend. The three places that spend against an allowance affirm the state they permit rather than listing the ones they refuse, so a status they do not recognise is refused rather than admitted.

The status flip and the evidence row are one transaction, and the UPDATE is guarded on the status this request read.

Who may call it: a project API key or an OAuth token holding mandates:write, or the dashboard acting for a verified admin or owner (x-codespar-user-token). The evidence row and the commerce.mandate.* event name the actor as actor_kind and actor_id.

POST /v1/consumers/mandates/{id}/pause is the legacy spelling, kept for two releases (ent#979): same handler, same mandates:write scope.

Path parameters

Request body

Responses

Response 200

curl -X POST https://api.codespar.dev/v1/mandates/{id}/pause \
  -H "Authorization: Bearer $CODESPAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "reason": "string"
     }'

POST /v1/mandates/{id}/pause HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEY
Content-Type: application/json

{
  "reason": "string"
}

import os
import requests

res = requests.post(
    "https://api.codespar.dev/v1/mandates/{id}/pause",
    headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"},
    json={
      "reason": "string"
    },
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://api.codespar.dev/v1/mandates/{id}/pause", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "reason": "string"
  }),
});

const data = await res.json();

const r = await cs.api.response("post", "/v1/mandates/{id}/pause", {
  path: {
    id: "mandate_0000000000000000"
  },
  body: {
    reason: "string"
  }
});
// r.status is one of the documented statuses (200, 403),
// each with its own body shape in r.data; nothing here throws on 403.
if (r.ok) {
  console.log(r.data);
}

{
  "mandate": {
    "id": "obj_0000000000000000",
    "status": "paused"
  },
  "changed": true
}

POST /v1/mandates/{id}/resume

Resume a paused allowance

Moves a paused allowance back to active. paused is the only legal source, so a revoked allowance answers 409 and does not come back to life.

Caps and expiry are untouched: the UPDATE sets status and updated_at and nothing else, so the allowance resumes with the spend it had already used still counted against it. Resuming an allowance whose expires_at has passed is legal here and still buys nothing, because the spend path refuses an expired mandate on its own.

Who may call it: a project API key or an OAuth token holding mandates:write, or the dashboard acting for a verified admin or owner (x-codespar-user-token). The evidence row and the commerce.mandate.* event name the actor as actor_kind and actor_id.

POST /v1/consumers/mandates/{id}/resume is the legacy spelling, kept for two releases (ent#979): same handler, same mandates:write scope.

Path parameters

Request body

Responses

Response 200

curl -X POST https://api.codespar.dev/v1/mandates/{id}/resume \
  -H "Authorization: Bearer $CODESPAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "reason": "string"
     }'

POST /v1/mandates/{id}/resume HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEY
Content-Type: application/json

{
  "reason": "string"
}

import os
import requests

res = requests.post(
    "https://api.codespar.dev/v1/mandates/{id}/resume",
    headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"},
    json={
      "reason": "string"
    },
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://api.codespar.dev/v1/mandates/{id}/resume", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "reason": "string"
  }),
});

const data = await res.json();

const r = await cs.api.response("post", "/v1/mandates/{id}/resume", {
  path: {
    id: "mandate_0000000000000000"
  },
  body: {
    reason: "string"
  }
});
// r.status is one of the documented statuses (200, 403),
// each with its own body shape in r.data; nothing here throws on 403.
if (r.ok) {
  console.log(r.data);
}

{
  "mandate": {
    "id": "obj_0000000000000000",
    "status": "active"
  },
  "changed": true
}

POST /v1/mandates/{id}/revoke

Revoke an allowance

Moves an active or paused allowance to revoked, and there is no verb here that moves it back: resume accepts paused only. An expired allowance answers 409, because expiry is already terminal for spending and revoking it would only rewrite which terminal state the evidence log records.

Revoking stops the spend on the same three gates that pausing does.

Who may call it: a project API key or an OAuth token holding mandates:write, or the dashboard acting for a verified admin or owner (x-codespar-user-token). The evidence row and the commerce.mandate.* event name the actor as actor_kind and actor_id.

POST /v1/consumers/mandates/{id}/revoke is the legacy spelling, kept for two releases (ent#979): same handler, same mandates:write scope.

Path parameters

Request body

Responses

Response 200

curl -X POST https://api.codespar.dev/v1/mandates/{id}/revoke \
  -H "Authorization: Bearer $CODESPAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "reason": "string"
     }'

POST /v1/mandates/{id}/revoke HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEY
Content-Type: application/json

{
  "reason": "string"
}

import os
import requests

res = requests.post(
    "https://api.codespar.dev/v1/mandates/{id}/revoke",
    headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"},
    json={
      "reason": "string"
    },
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://api.codespar.dev/v1/mandates/{id}/revoke", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "reason": "string"
  }),
});

const data = await res.json();

const r = await cs.api.response("post", "/v1/mandates/{id}/revoke", {
  path: {
    id: "mandate_0000000000000000"
  },
  body: {
    reason: "string"
  }
});
// r.status is one of the documented statuses (200, 403),
// each with its own body shape in r.data; nothing here throws on 403.
if (r.ok) {
  console.log(r.data);
}

{
  "mandate": {
    "id": "obj_0000000000000000",
    "status": "revoked"
  },
  "changed": true
}