Registering principals
A principal is the legal person behind an agent — the company or individual that owns it, funds it, and answers for what it does. Every agent has one, and no agent can be registered without one. This is where accountability stops being a property of software and becomes a property of someone real.
Your platform onboards principals, verifies them, and holds the commercial relationship with them. Nustro records the principal and its verification, then issues certificates against it. A principal never talks to Nustro directly, and Nustro never invoices one.
What a principal is, and is not
| A principal is | A principal is not |
|---|---|
| The legal entity or individual that owns one or more agents | A user account — principals have no login and no dashboard |
| The party whose verification backs every certificate you issue for its agents | An agent — agents are registered separately and belong to a principal |
| The holder of the operational wallet keys and the recipient of settlement proceeds | A Nustro Customer — in this API a Customer is a client of yours; your platform’s own relationship with Nustro is the Platform account |
A principal may be a supplier, a buyer, a service vendor, or all three at once depending on the roles its agents hold. “Merchant” presumes a selling relationship that often is not there, and it is not a term the protocol uses. Principal is the word in your UI, your API, and your support macros.
Your own tenant principal
Your platform is itself a principal — the one that owns any agents you operate directly rather than on a customer’s behalf. Nustro creates it automatically when your account is provisioned, seeded from your company profile.
| Property | Behaviour |
|---|---|
| Creation | Automatic, at account provisioning. You do not register it. |
| Editing | Read-only through the principals API — it is maintained from your company profile so there is one writer, not two. |
| Counts and reporting | Excluded from principal listings and never groupable under a Customer — it is you, not a customer of yours. |
| Agents | Registered against it exactly like any other principal’s. |
The Verifier
Verification is not performed by Nustro. A Verifier is an independent party that runs the compliance checks and issues a signed, time-bound Verification Attestation. Your platform sources that attestation and passes it to Nustro, which issues certificates against it and never re-verifies.
| Party | Does | Does not |
|---|---|---|
| Your platform | Sources verification — runs it in-house if accredited, otherwise arranges it with an independent Verifier. Gates activation on the attestation. | Attest to its own principals without meeting the Verifier requirements |
| Verifier | Runs the checks, signs the attestation, renews and revokes it | Belong to the principal it verifies — a principal cannot self-attest |
| Nustro | Records the attestation, enforces what it permits, issues certificates | Verify principals, hold your documents, or choose your Verifier |
Where accredited to do so, a platform may operate the Verifier role itself and be the single surface a principal ever sees. Independence is the constraint that matters: the Verifier cannot be the principal being verified. Most platforms arrange verification with a third party and pass the attestation through.
A Verifier must be independent of the principal, capable of the checks its tier requires, cryptographically identifiable, and able to renew and revoke what it issues. Multiple Verifiers operate in the ecosystem, and counterparties can inspect which one attested a principal.
Independence, compliance capability, cryptographic identity, accountability, and attestation lifecycle management are protocol requirements, not Nustro policy. AEA/P §5.2.3. Read §5.2 ↗
A Verification Attestation (§5.2) is what a Verifier issues about a principal,
and it is what the activation gate checks. An Agent Attestation (§5.7) is a
separate, optional credential attached to an agent — and those gate nothing:
they are advisory and can never reject a transaction. The one exception is
portability: an identity-class Agent Attestation from a Trust-Registry
recognised Verifier may satisfy the activation requirement without re-running
verification. Non-identity types — compliance.*, capability.*, risk.* —
never qualify.
What gets verified
The requirement is role-differentiated — matched to what the principal’s agents will be allowed to do, rather than applied uniformly.
| If its agents will be… | Required tier | Because |
|---|---|---|
| Consumer agents | Tier 1 — identity and sanctions screening. In the Nustro implementation this is satisfied by address verification: a card authorization on a live instrument, or an address document. | Consumers only spend their own funds under declared limits. There is no counterparty exposure to underwrite. |
| Provider agents | Tier 2 — Tier 1 plus business registration and beneficial ownership verification. | Providers take payment before delivering and carry escrow. Someone must be identifiable when a dispute goes against them. |
| Enterprise agents | Tier 3 — Tier 2 for each principal, plus cross-principal and PEP screening, source of funds, and ongoing AML monitoring. | Enterprise agents do both, at scale, with governance rights over other agents. |
The coupling is normative, and the protocol assigns the gate to the Platform: a compliant platform MUST NOT activate an agent whose principal’s attestation is below the role’s required tier. Nustro issues against whatever attestation you reference and does not re-verify — so check the tier before you activate, not after. AEA/P §5.2.1. Read §5.2 ↗
Attestations expire
An attestation is time-bound — typically no more than twelve months — because compliance status changes. Sanctions designations appear, businesses dissolve, ownership moves.
| Event | Effect |
|---|---|
| Attestation expires | Every agent under the principal transitions to SUSPENDED. New transactions stop; open disputes continue to resolution. |
| Verifier revokes it | Same effect, immediately — for example on a sanctions designation. |
| Re-verification completes | A new attestation is issued and agents can be returned to ACTIVE. |
| Principal takes on a higher role | A new attestation at the higher model is required before the role change takes effect. |
Suspension on expiry is automatic and gives no grace period. Your platform holds
the principal relationship, so it is the only party positioned to start
re-verification before the deadline — drive it from the attestation’s
expires_at, not from a support ticket.
Registering a principal
One call, after your verification completes.
curl -X POST https://api.nustro.com/v1/principals \
-H "Nustro-Api-Key: nustro_sandbox_••••" \
-H "Idempotency-Key: 5a91f7c2-0b3d-4c8e-9a17-6de4820cb193" \
-d '{
"legal_name": "Northwind Operations Ltd",
"country": "GB",
"entity_type": "company",
"verification_attestation": {
"attestation_id": "att_4c81a20e",
"verifier_id": "vrf_northgate_compliance",
"model": "kyb",
"issued_at": "2026-05-02T00:00:00Z",
"expires_at": "2027-05-02T00:00:00Z"
}
}'| Field | Notes |
|---|---|
legal_name | As it appears on the registration document, not a trading name. |
country | ISO 3166-1 alpha-2. Derives the principal’s market and its available jurisdictions — get it wrong and its agents cannot be configured for the right markets. |
entity_type | company or individual. |
customer_id | Optional, nullable. Groups the principal under one of your Customers — a client of yours; null ungroups. Set or move later via PATCH. Filter principals with ?customer_id=<cid>, or ?customer_id=none for the ungrouped. |
verification_attestation | The attestation your Verifier produced — its id, the verifier_id that signed it, the model performed, and its validity window. |
Nustro records the attestation, not your evidence. Keep the underlying documents
and the attestation_id on your side — when a dispute escalates or an auditor
asks how a certificate came to exist, that identifier is the thread back to the
file.
Principal lifecycle
| State | Meaning | Agents can transact? |
|---|---|---|
ACTIVE | Verified and in good standing | Yes |
ATTESTATION_EXPIRED | The verification has aged out and needs renewal | No — its agents are suspended until re-verified |
SUSPENDED | Suspended by your platform | No |
CLOSED | Offboarded. Agents are revoked; settled history and open disputes are retained | No |
A principal’s state propagates to its agents. Suspension, closure, and attestation expiry all cascade to every agent underneath — there is no per-agent exemption.
Common errors
| Code | Status | What it means |
|---|---|---|
validation_failed | 422 | Not a valid ISO 3166-1 alpha-2 code, or a jurisdiction Nustro does not currently operate in. Field-level, in field_errors. |
validation_failed | 422 | No attestation supplied. Complete verification before registering. |
validation_failed | 422 | The attestation is older than the permitted age for its model. Re-verify. |
validation_failed | 422 | customer_id references an unknown Customer, or one belonging to another platform. Named in field_errors. |
tenant_principal_field_locked | 409 | Customer grouping attempted on your own tenant principal — it is you, and never groups under a Customer. |
external_ref_exists | 409 | A principal with this legal name and country already exists for your platform. Re-read it rather than creating a duplicate. |
close_blocked_open_disputes | 409 | Closure attempted while agents are active or disputes are open. |