Core concepts
Mandate Labs is built on a small set of objects arranged in a hierarchy. Understanding how they nest — and why each layer exists — is the foundation for every integration.
Overview
Every action on the platform — onboarding a user, registering an agent, authorizing a payment — maps to one of six objects. They form a single ownership chain from the contracting organization down to an individual transaction decision:
Client → Program → Principal → Agent → Mandate → Authorization.
The split isn't arbitrary. It separates the three things a payments platform has to keep distinct: who is accountable (the Client and the Principal it KYC's), what is allowed (the Program's rails and the Mandate's limits), and what actually happened (the Authorization and its outcome). That separation is what lets one verified identity safely run many autonomous agents.
The object hierarchy
A Client is the tenant. It owns one or more Programs (the rails + policy) and onboards Principals (the people or merchants it has verified). Each Principal owns one or many Agents; each Agent is bounded by one or more Mandates; and every transaction an Agent attempts produces an Authorization.
A Principal is one stable prn_ that owns many Agents — you never mint a new Principal per agent. Add the 2nd…Nth agent to the same Principal. One KYC'd identity, many autonomous agents.
The objects
Client cli_
The contracting organisation and the tenant boundary. Every other object belongs to exactly one Client. The Client holds the API credentials, is the party Mandate Labs has a commercial agreement with, and is the obligated entity for compliance.
Program prg_
A card and/or crypto program under a Client. It carries the enabled rails (card, crypto), program-level default limits, BIN/sponsor binding, and the verification mode. A Client can run several Programs (e.g. a card program and a stablecoin program), and a Principal can be enrolled in more than one.
Principal prn_
A person or merchant the Client onboards and the platform KYC/KYB-verifies — not the contracting organisation (that's the Client). A Principal is the accountable identity behind the agents: it carries the verification status, the risk tier, and the Client's own customer reference (client_customer_ref) so a transaction can always be traced back to a real, verified subject.
Agent agt_
An AI system that transacts on behalf of a Principal. Each Agent gets a unique id and a DID, starts at the REGISTERED trust level, and accrues a behavioural Decision-Trust (KYA) score over time. A Principal can own many Agents; each is independently scored and bounded.
Mandate mnd_
The spending authority granted to an Agent: max amount per transaction, daily/monthly limits, allowed merchant categories (MCCs), allowed countries, rails, and an expiry. An Agent transacts only within the bounds of an active Mandate; everything outside is declined before it reaches the trust engine.
Authorization auth_
The decision record for a single transaction. Every request an Agent makes produces an Authorization with a verdict — APPROVE, STEP_UP, or DECLINE — plus the KYA score, risk signals, and full reason codes. Authorizations are the immutable, queryable history of what every agent did and why.
Relationships
The cardinalities that matter when you model your integration:
| From | To | Cardinality | Notes |
|---|---|---|---|
| Client | Program | 1 → many | A Client runs one or more rails programs. |
| Client | Principal | 1 → many | Every Principal belongs to exactly one Client. |
| Principal | Program | many ↔ many | A Principal enrols in one or more of its Client's Programs. |
| Principal | Agent | 1 → many | The core invariant — one identity, many agents. |
| Agent | Mandate | 1 → many | An agent can hold multiple mandates (e.g. card + crypto). |
| Agent | Authorization | 1 → many | Every transaction attempt is recorded. |
| Client | API credential | 1 → many | Credentials are held at the Client, optionally scoped per Program/env. |
The lifecycle
How the objects come into being, end to end:
- Provision the Client. After a sales/KYB conversation, Mandate Labs creates the Client and a default Program and issues the Client's API credential.
- Onboard a Principal. The Client onboards a person or merchant (
POST /principals) and enrols them in a Program — verified client-attested (immediate) or platform-provider (pending KYC). - Register Agents. The Client adds one or more Agents under that same Principal (
POST /principals/{prn}/agents). - Grant Mandates. Each Agent gets a Mandate (
POST /agents/{agt}/mandates) bounding what it may spend. - Authorize. The Agent requests authorization for each transaction (
POST /authorize) and receives APPROVE / DECLINE / STEP_UP in real time. - Close the loop. Settlement and dispute outcomes feed back, the Agent's trust score updates, and webhooks notify your systems.
Steps 2–4 can be done in one call with the POST /onboard bundle for quickstart and sandbox; the decoupled endpoints stay canonical for adding more agents later.
Two ways in
How you obtain the objects depends on whether you're experimenting or going live: