Mandate and governance

Four executable commands govern what an agent is allowed to spend and on what instrument: codespar mandate create mints the authority, codespar mandate verify checks a presentation token a counterparty handed you, codespar issue creates and controls the card the authority is spent on, and codespar verification-status reads where an asynchronous KYC inquiry landed. mandate is a command group with those two leaves; issue and verification-status are top level.

Two commands that do not exist

codespar mandate show and codespar mandate revoke are not in the shipped binary. Measured with codespar mandate --help, which lists exactly create, verify and help and nothing else. There is no CLI path to read a mandate back or to revoke one; the lifecycle beyond creation is described in Mandates.

Shared behaviour

These root options are declared on the program, not on the subcommands, and apply to all four. Commander accepts --json in either position: codespar --json mandate verify <token> and codespar issue --input '{...}' --json were both measured and both emitted JSON.

Credentials resolve flag first, then environment (CODESPAR_API_KEY, CODESPAR_PROJECT, CODESPAR_BASE_URL), then ~/.codespar/config.json, which login writes with mode 0600. Three of the four commands refuse immediately without a key; mandate verify is the exception and is documented below.

Channels are split by design. Tables, key/value blocks and JSON go to stdout; the ✓, ℹ and ⚠ lines go to stderr. In human mode codespar issue and codespar verification-status write nothing at all to stdout, which is worth knowing before you pipe them.

Exit codes

Measured on these four commands, with the command that produced each.

codespar mandate create collapses the first two stops into one call: it mints the consent token and then submits the consumer leg itself, so the hosted consent page is skipped and the terminal stands in for the consumer. The third stop stays on the server, which is why the command comes back with a mandate_id and never with a key. codespar mandate verify checks those signatures again from outside, codespar issue creates the card the fourth stop spends on, and the mandate id goes to codespar spend. The rest of that stop is out of reach here: with no codespar mandate revoke in the binary, pausing or revoking an authority happens off the CLI.

codespar mandate create

Runs the two-leg directed-pay consent flow from your terminal: it mints a one-shot consent token carrying the intent (purpose, caps, currency or slots, payee allowlist), then submits the consumer side against that token, which is what provisions the funding source and signs the mandate. It prints the mandate id you hand to codespar spend.

The first leg carries your API key; the token in the second leg's URL is the authentication, so the bearer header there is ignored. Two notes on those routes, both measured against the committed OpenAPI snapshot. POST /v1/consents/init is in the published document and marked deprecated there, as an alias of POST /v1/consents kept for two releases; the CLI still calls the alias. POST /v1/consents/{token}/submit is not in the published document (ent#1186): it is the leg the consumer's browser is meant to call, and this command calls it from the tenant's terminal. See Mandates for why that leg is kept out of the client surface.

Flags

Two rules are worth stating in prose because they are not visible in the flag list. --slot wins. When at least one --slot is given, --cap, --per-tx-cap and --currency are ignored, and the top of the intent mirrors the first slot: its cap, its per-transaction cap and its currency. The rail on the submit leg is not the slot's rail. Each slot carries its own rail inside intent.slots; the --rail value only satisfies the submit schema, so leaving the default in place on a multi-slot mandate is expected and was measured doing exactly that.

--pin-kind and --currency are checked against the vocabularies the consent contract declares, so a typo fails at your terminal instead of at the end of a consent ceremony:

✗ --pin-kind expects one of pix-key, merchant-id, mcc, got "inventado".
✗ --currency expects one of BRL, USD, MXN, COP, ARS, USDC, BRLA, got "EUR".

Example

codespar mandate create \
  --consumer con_9x1 \
  --agent agt_7fa21c \
  --purpose "Compras do mes" \
  --payee "loja@empresa.com.br" \
  --slot BRL:pix-celcoin:50000:10000 \
  --slot USDC:usdc-onchain:100:25

mandate    cm_4f19ab
consumer   con_9x1
agent      agt_7fa21c
purpose    Compras do mes
allowlist  loja@empresa.com.br
slots      BRL/pix-celcoin cap 50000 (per-tx 10000)  |  USDC/usdc-onchain cap 100 (per-tx 25)

✓ multi-slot mandate created
ℹ One signature, 2 currencies — caps are per-currency (no FX).
  See the wallet:  codespar wallet con_9x1
  Spend:           codespar spend --mandate cm_4f19ab --payee loja@empresa.com.br --amount 1 --agent agt_7fa21c

The caps in that call are minor units, per currency, with no conversion between slots: 50000 and 10000 are R$ 500,00 total and R$ 100,00 per transaction on the BRL slot, 100 and 25 are the USDC slot's own numbers.

With the single-currency form (--cap 10000 --per-tx-cap 2500, no --slot), the block changes shape: per-tx cap, total cap and rail rows replace the slots row, and the values are labelled with --currency, which defaults to USDC.

With --json, stdout carries the submit response and nothing else, and stderr is empty. The init response is not printed in either mode.

{
  "mandate_id": "cm_4f19ab",
  "consumer_id": "con_9x1",
  "status": "active",
  "expires_at": "2026-09-13T18:00:00Z"
}

Refusals

Every row below was run. Validation of caps, TTL and slots happens before any request, so a malformed call costs no round trip.

The last row is the general shape for an HTTP failure on this command: verb, path, status, then the message the API sent. A scope refusal and a validation refusal are indistinguishable by exit code; the text is what separates them.

codespar mandate verify

Decodes a base64url presentation token, rebuilds the canonical signing string from the fields it carries, and checks the Ed25519 signatures against keys you supply or against the did:web documents it resolves. It is the only command on this page that runs with no API key: it loads the config for a base URL and never calls requireApiKey. Measured with CODESPAR_API_KEY emptied, and it printed the full report.

There is no REST route behind the offline path. In network mode it fetches DID documents, described below.

Arguments and flags

Either pubkey flag switches the whole command to offline: zero network calls, both signatures checked against what you passed. With neither flag it runs in network mode and resolves keys from DID documents. There is no flag that forces network mode while a key is supplied.

Keys are 64 hex characters, a leading 0x is tolerated and case is ignored. Anything else is refused before the token is touched.

What counts as verified

A token passes when at least one carried signature verified and none failed. In offline mode a signature whose key you did not supply is reported skipped, which neither passes nor fails on its own: a token with a good agent_sig and no --issuer-pubkey exits 0 with the issuer line marked skipped. That was measured, and it is the behaviour to read carefully before treating this command as a gate.

Expiry is reported, not enforced. A token whose expires_at was in the past, with both signatures good, printed [expired] next to the timestamp and still exited 0 with verified. If expiry matters to your check, read expired out of the --json body yourself.

The principal's document is never printed. Human output prints principal_kyc present or absent; --json emits principal_kyc_ref_present as a boolean. The CPF or CNPJ reference itself is redacted in both.

Example

codespar mandate verify "$TOKEN" \
  --agent-pubkey 2abe98d728d767007bb7329e9d1f1d7f107b2f1288457291f300ece461349b87 \
  --issuer-pubkey 272b1badc6c62899dc5a1a1c25f09b06ab57db69e31e938ac30791c7bee9f17a

signatures
agent_sig   ✓ verified  kid did:web:id.codespar.dev:acme:shopper#1  via flag
issuer_sig  ✓ verified  via flag

mandate
id             mnd_3xq8w2
agent_id       agt_7fa21c
agent_did      did:web:id.codespar.dev:acme:shopper
kid            did:web:id.codespar.dev:acme:shopper#1
type           payment
amount         50000 BRL
max_amount     10000 BRL
purposes       groceries, delivery
principal_kyc  present
expires_at     1789913600 (2026-09-20T14:13:20.000Z)
format         v3

✓ mandate token verified (offline mode)

Corrupt agent_sig in that token and the same call exits 1: the report still prints in full, the agent line reads ✗ failed, the issuer line still reads ✓ verified, and stderr adds ⚠ mandate token NOT verified (offline mode) plus a line saying a carried signature failed or could not be checked. That is the shape to key a gate on, because a single bad signature is enough to fail the token even when the other one verified.

The --json body of the passing run:

{
  "verified": true,
  "mode": "offline",
  "format_version": 3,
  "signatures": {
    "agent_sig": { "present": true, "status": "verified", "kid": "did:web:id.codespar.dev:acme:shopper#1", "source": "flag", "detail": null },
    "issuer_sig": { "present": true, "status": "verified", "kid": null, "source": "flag", "detail": null }
  },
  "mandate": {
    "id": "mnd_3xq8w2",
    "agent_id": "agt_7fa21c",
    "agent_did": "did:web:id.codespar.dev:acme:shopper",
    "kid": "did:web:id.codespar.dev:acme:shopper#1",
    "type": "payment",
    "amount": "50000",
    "currency": "BRL",
    "max_amount": "10000",
    "parent_id": null,
    "denomination": null,
    "purposes": ["groceries", "delivery"],
    "principal_kyc_ref_present": true,
    "expires_at": 1789913600,
    "expires_at_iso": "2026-09-20T14:13:20.000Z",
    "expired": false,
    "format_version": 3
  }
}

A token that fails to decode answers in the same channel it would have used: --json prints { "verified": false, "error": "mandate_format_unsupported" } and exits 1, while the human mode throws the message as an ordinary refusal.

Network mode

Without a pubkey flag the command resolves keys over the network, trying two URLs in order and stopping at the first that yields an Ed25519 key: the standard did:web mapping (https://<host>/.well-known/did.json, or https://<host>/<path>/did.json when the DID carries path segments), then the API fallback at <base-url>/v1/agents/<did>/did.json. Only OKP / Ed25519 entries of exactly 32 bytes are taken from a document's verificationMethod; everything else is skipped. When the token names a key id, keys matching it are tried first. A document that cannot be fetched, or that carries no usable key, is a failure in network mode, not a skip. Each fetch has its own 15 second budget.

Refusals

codespar issue

Opens a throwaway session with no servers, calls the codespar_issue meta-tool through it, and closes the session in a finally whether the call succeeded or not. There is no --server: the meta-tool router picks the issuing rail.

Measured on the stub, one invocation is three requests: POST /v1/sessions with body {"servers":[],"user_id":"cli-user"}, then the execute above with {"tool":"codespar_issue","input":{...}}, then DELETE /v1/sessions/<id>.

Flags

--input and --input-file are mutually exclusive, and one of them is mandatory. The payload has to parse as a JSON object: an array or a scalar is refused by name.

The arguments the CLI checks

This table is the subset the CLI validates locally, before opening a session. It is not the schema of the meta-tool, which has more fields and is the authority on all of them; for that, read codespar_issue.

Example

codespar issue --input '{
  "action": "card-virtual",
  "cardholder_id": "usr_123",
  "program_id": "afg_123"
}'

✓ issue card-virtual → active
ℹ Card id: crd_7bd2f1
ℹ Type: virtual
ℹ Last four: 4417
ℹ Cardholder: usr_123

Stdout really is empty there. The human path prints the status line and then four conditional lines, one each for id, card_type, last_four and cardholder_id, and every one of them goes to stderr. Pass --json and the relationship inverts: stdout carries the result object and stderr is empty.

{
  "id": "crd_7bd2f1",
  "status": "active",
  "card_type": "virtual",
  "last_four": "4417",
  "cardholder_id": "usr_123"
}

That object is the stub's, shaped to exercise the five fields the CLI reads. The real result shape of codespar_issue was not verified here. The status in the first stderr line falls back to the literal ok when the result carries no status.

Refusals

Two of those messages are long enough that a table cell mangles them. Verbatim:

✗ issue requires --input '<json>' or --input-file <path>. Example: --input '{"action":"card-virtual","cardholder_id":"usr_123","program_id":"afg_123"}'
✗ issue.control (freeze | unfreeze | cancel) is required when action=card-control.

The last row of the table covers a scope refusal, a provider rejection and a genuine bug alike. Measured twice: a stub answering {"success":false,"error":"cardholder not found in program afg_123"} and a stub answering 403 insufficient_scope both produced exit 2 with a stack, the only difference being the text after issue failed:.

codespar verification-status

Opens a throwaway session and reads where an asynchronous KYC inquiry landed for one tool call, once by default, or holding an event stream open until the terminal frame with --stream.

The streaming form reads /v1/tool-calls/{id}/verification-status/stream instead. Both are in the published document; see Tool calls for the response schema, and verificationStatus for the typed wrapper this command is built on.

Arguments and flags

--timeout must be a positive number and is checked before the session opens. It applies to the stream; the one-shot read does not use it.

Example

codespar verification-status tcl_kyc_9a1

✓ verification_status: approved
ℹ tool_call_id: tcl_kyc_9a1
ℹ original_status: pending
ℹ idempotency_key: idem_5c2e
ℹ hosted_url: https://verify.codespar.dev/i/inq_44a2
ℹ events: 2

As with issue, the human mode leaves stdout empty. idempotency_key falls back to - when absent; hosted_url is the one line printed only when the field is there, and apart from the label on the first line it is the only thing that separates this rendering from its settlement twin codespar payment-status, which prints the same four remaining lines and has no hosted_url field at all. events is the count, not the list: to see the events themselves, use --json, which puts the whole result object on stdout unchanged.

{
  "tool_call_id": "tcl_kyc_9a1",
  "verification_status": "approved",
  "original_status": "pending",
  "idempotency_key": "idem_5c2e",
  "hosted_url": "https://verify.codespar.dev/i/inq_44a2",
  "events": [
    { "at": "2026-09-12T18:02:11Z", "status": "pending" },
    { "at": "2026-09-12T18:04:39Z", "status": "approved" }
  ]
}

Refusals

The last row was measured against a stub answering 403 insufficient_scope. The same caution as issue applies: 2 here is a refused call, not a crash.