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 what its agents do. “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. Your platform verifies each principal — in-house, or through a verification provider it chooses — and asserts the result to Nustro as the principal’s Verifier: a signed, time-bound Verification Attestation carrying its tier. Nustro records it, carries the tier in each of the principal’s agents’ certificates, and checks it against each agent’s type. It never re-verifies.
| Party | Does | Does not |
|---|---|---|
| Your platform | Verifies the principal, or arranges it with a provider. Asserts the tier — inline when it creates the principal, or with PUT /v1/principals/{pid}/verification — and renews it before it expires. | Assert a tier its checks do not support, or assert production tiers before it is accredited |
| Verification provider | Runs identity, business-registration and sanctions checks for your platform, if you use one | Talk to Nustro — its result reaches Nustro only through your assertion |
| Nustro | Records the assertion, re-signs the principal’s agents with the tier, and rejects an agent whose type the tier does not meet | Verify principals, hold your documents, or choose your provider |
The asserting platform is the Verifier: the verifier_id on the record is your
platform_id, and a principal sees only your platform. Independence is the
constraint that matters — the Verifier cannot be the principal being verified.
In sandbox you can assert any tier with no documents behind it; in production
only an ACCREDITED platform can assert one.
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 its tier is what Nustro checks against each agent’s type. 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 verification requirement
without re-running verification. Non-identity types — compliance.*,
capability.*, risk.* — never qualify.
What gets verified
The requirement follows the agent type — matched to whom the principal’s agents act for and whether they can be paid, rather than applied uniformly.
| If its agents will be… | Required tier | Because |
|---|---|---|
| Personal agents | Tier 1 — identity and sanctions screening of a natural person. In the Nustro implementation this is satisfied by a card authorization on a live instrument, or an address document. The principal must be an individual. | A personal agent only spends its principal’s own funds under declared limits. There is no counterparty exposure to underwrite. |
| Business agents | Tier 2 — Tier 1 plus business registration and beneficial ownership verification. A sole proprietor’s business license satisfies business registration. | A business agent may be paid, and one that sells takes payment before delivering and carries escrow. Someone must be identifiable when a dispute goes against it. |
| Business agents governed by several principals | Tier 3 — Tier 2 for each principal, plus cross-principal and PEP screening, source of funds, and ongoing AML monitoring. | Shared control is accountable only when every party behind it is. Multi-principal governance is on the Nustro roadmap. |
The coupling is normative (AEA/P §5.2.1), and Nustro applies it at registration,
activation and environment switch: an agent whose principal’s tier is below its
type’s requirement is rejected with verification_tier_insufficient, and a
personal agent under a company principal with principal_type_mismatch. What
Nustro cannot check is the verification behind the tier — so assert only what
your checks support. 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. |
| A personal agent is upgraded to business | The principal needs a Tier 2 verification first — assert it with PUT /v1/principals/{pid}/verification, then upgrade the agent. The new verification replaces the old one and re-signs every agent under the principal. |
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. Assert the tier inline once your verification completes, or create the
principal first and assert it later with PUT /v1/principals/{pid}/verification —
no agent can be registered under it until it has a tier.
curl -X POST https://api.nustro.com/v1/principals \
-H "Nustro-Api-Key: nustro_sandbox_••••" \
-H "Idempotency-Key: 5a91f7c2-0b3d-4c8e-9a17-6de4820cb193" \
-d '{
"display_name": "Northwind Operations Ltd",
"email": "ops@northwind.example",
"principal_type": "company",
"country": "GB",
"external_ref": "crm-00417",
"verification": {
"verification_tier": "TIER_2",
"checks_performed": ["identity", "kyb", "sanctions"],
"expires_at": "2027-05-02T00:00:00Z"
}
}'| Field | Notes |
|---|---|
display_name | The principal’s name — for a company, as it appears on the registration document, not a trading name. |
email | The notice address for dispute and violation emails about this principal’s agents. |
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. |
principal_type | company or individual. A personal agent needs an individual principal. |
external_ref | Your own identifier for the principal, unique within your platform. Deduplication works on it. |
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 | Your assertion: the verification_tier (TIER_1, TIER_2 or TIER_3), the advisory checks_performed, and expires_at — at most twelve months out, twelve by default. Nustro adds the attestation_id and your platform as verifier_id. |
Nustro records the assertion, 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 | verification.expires_at is in the past or more than twelve months out. |
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 external_ref 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. |