Stable field names
Reference
Once a name is published, changing it breaks a customer's integration. These are the names we are committing to for this version. Two rules govern them: a public name describes the outcome, never the mechanism; and a name only appears here when something answers to it.
Tool names
Field names
Field Where Means How a name can change Only by a new dated version. The old name keeps working for twelve months and returns a deprecation header for the last ninety days. Nothing is renamed inside a version, including in the MCP server. See also MCP server → Errors & refusals →
Fields
| Field | Where | What it means |
|---|---|---|
| facetoken | Identity, Mandates | The durable handle you store in place of a person. Stable for you, meaningless elsewhere, carries no biometric. |
| granted_by | Mandates | The human who authorised, proven alive at the moment of the grant. |
| granted_to | Mandates | The agent that may act. |
| scope | Mandates | access · data_release · payment · signature. |
| ceiling | Mandates | amount · currency · count · period · counterparties. |
| until | Mandates | Absolute expiry. |
| require | Mandates | proof_of_live_human. |
| allowed | Check | The answer. Branch on this, never on the HTTP status. |
| reason | Check | Why an action was refused. Null when allowed. |
| remaining | Mandates, Check | What is left of the ceiling. |
| receipt | Everywhere | id · anchor · url. Anchored proof that the answer was given. |
| metadata | Identity, Mandates | Your own strings, returned unchanged, never in a public receipt. |
| state | Verify | verified · pending · not_found. The seal, never the substance. |
| seals | Receipts | What was proven: proof_of_live_human, identity_matched, mandate_granted, settlement_sealed. |
| anchor | Receipts | The public-record entry a receipt is checked against. Null while pending. |
| mode | Hosted | claim · recognise · attribute · mandate. One session does one thing. |
| return_url | Hosted | Where the person lands when the session ends. https, on a registered host. |
| branding | Hosted | logo_url · accent · domain · headline · footer_note. White-label, free tier. |
| result | Hosted | What the session produced. The authoritative outcome, not the redirect query string. |
MCP tools
| Tool | Endpoint | What it does |
|---|---|---|
| identity_claim | identity-claims | Claim a coordinate for a person. Billed once per person, for life. |
| identity_recognise | identity-recognitions | Recognise a person already claimed. Free, at any volume. |
| identity_attribute_request | identity-attributes | Ask for one attribute and receive the answer, never the document. |
| mandate_create | mandates-create | Issue a mandate from a live human's grant. |
| mandate_list | mandates-list | List mandates by granter, agent or status. |
| mandate_get | mandates-get | Retrieve one mandate and its remaining ceiling. |
| mandate_check | mandates-check | Ask whether an action fits the mandate. Returns allowed with a reason. |
| mandate_revoke | mandates-revoke | Revoke a mandate. Effective on the next request, never billed. |
| receipt_get | receipts-get | Retrieve a full receipt, for a party to the transaction. |
| receipt_verify | receipts-verify | Check a receipt against the public record. No key required. |
| session_create | sessions-create | Open a hosted session and get a URL to redirect the person to. |
| session_get | sessions-get | Read the outcome of a hosted session. |