Documentation Index
Fetch the complete documentation index at: https://docs.nxos.io/llms.txt
Use this file to discover all available pages before exploring further.
This guide explains how a broker organization operates the API on behalf of customer organizations through a single API key, and how to revoke that access when the relationship ends.
When you’d use this
The everyday case is a broker (a regulated counterparty that owns the client relationship) serving multiple customer organizations through a single platform integration. Each customer has their own org, accounts, balances, and funding methods. The broker holds an API key and operates on each customer’s behalf one request at a time.
Examples:
- A private-broker program where each high-net-worth client has their own org but is operated by the broker’s desk.
- A platform that white-labels nxos for partner firms, each managing their own clients.
- A treasury operations team that consolidates several legal entities under one operating team.
If your integration only ever acts on its own org, skip this guide.
The model
With an LOA, one organization is authorized to act on behalf of another via the platform API. The granting organization (the customer) signs the LOA; the authorized organization (the broker) holds it. Once active, the broker sends requests with the Nxos-On-Behalf-Of header set to the customer’s org id, and the platform scopes the request to the customer’s data.
Signing happens as part of the customer’s verification flow. Revoking ends access; re-establishing it requires a new grant.
Lifecycle
signed revoke
PENDING ──────────────► ACTIVE ──────────────► REVOKED
│ ▲
└─────────────────── revoke ───────────────────┘
| Status | Meaning | Effective for Nxos-On-Behalf-Of? |
|---|
PENDING | Granter has not yet signed. | No |
ACTIVE | Granter has signed. | Yes |
REVOKED | Previously active or pending, now revoked. | No |
KYB gating
An ACTIVE LOA is necessary but not sufficient. The granting organization must also currently be in good standing on KYB (verification status APPROVED, no past-due expiry). If the granter’s verification moves to PENDING, ON_HOLD, REJECTED, or RESUBMISSION_REQUIRED, the LOA is suspended for that period and the broker’s requests return 403 authorization_required. Access resumes automatically when the granter returns to APPROVED.
From the broker’s perspective, this is indistinguishable from a missing LOA: the response is the same 403 authorization_required. The granter’s compliance status is not leaked to a third party.
Using Nxos-On-Behalf-Of
Once an LOA between customer org_cust... and broker org_brkr... is ACTIVE and the customer’s KYB is APPROVED, the broker calls any delegation-enabled endpoint by setting the header:
curl https://api.sandbox.nxos.io/v1/accounts \
-H "Authorization: Bearer nxos_sk_test_brkr..." \
-H "Nxos-On-Behalf-Of: org_cust1234567890abcdef1234567890abcd"
Nxos-On-Behalf-Of to a route that doesn’t accept delegation, the header is silently ignored and the request stays scoped to your own org. The default posture is default-deny: a route only sees data the caller has direct authority over unless it explicitly opts in.
Possible 403 responses
| Code | Meaning | Fix |
|---|
acting_org_not_found | The header points to an org that doesn’t exist. | Check the org id. |
authorization_required | The org exists, but you don’t hold a currently effective LOA on it. Possible reasons: the customer hasn’t signed, the grant was revoked, or the customer’s KYB is not currently APPROVED. | Check the LOA state in the dashboard, and confirm the customer’s verification status. |
Revoking an authorization
Either side of the grant can call POST /v1/authorizations/revoke: the granting customer or the authorized broker. The caller’s organization (from the API key) must be one of the two parties. Otherwise the call returns 403 forbidden.
curl -X POST https://api.sandbox.nxos.io/v1/authorizations/revoke \
-H "Authorization: Bearer nxos_sk_test_..." \
-H "Content-Type: application/json" \
-d '{
"grantingOrganizationId": "org_cust1234567890abcdef1234567890abcd",
"authorizedOrganizationId": "org_brkr1234567890abcdef1234567890abcd",
"type": "LOA",
"reason": "Client off-boarded"
}'
{
"object": "authorization",
"grantingOrganizationId": "org_cust1234567890abcdef1234567890abcd",
"authorizedOrganizationId": "org_brkr1234567890abcdef1234567890abcd",
"type": "LOA",
"status": "REVOKED",
"signedAt": "2025-12-01T10:30:00.000Z",
"revokedAt": "2026-05-15T14:30:00.000Z",
"revokedReason": "Client off-boarded",
"createdAt": "2025-12-01T10:30:00.000Z",
"updatedAt": "2026-05-15T14:30:00.000Z"
}
Revocation is immediate and permanent. The next request the broker makes with Nxos-On-Behalf-Of pointing at this customer returns 403 authorization_required. To re-establish access, the customer must sign a new LOA. There is no restore endpoint.
Idempotency
A second revoke of the same (granter, authorized, type) tuple returns 404 authorization_not_found. The row is already REVOKED and excluded from the active set. There is no separate already_revoked error code. “Already revoked” and “never existed” surface identically by design.
You can also supply an Idempotency-Key header for client-side dedup of network retries. See Idempotency.
Possible errors
| Status | Code | When |
|---|
400 | invalid_request | grantingOrganizationId == authorizedOrganizationId. |
400 | validation_error | Malformed org id (must be org_<32 hex>), or reason exceeds 500 characters. |
403 | forbidden | Your API key’s organization is neither the granter nor the authorized. |
404 | organization_not_found | One of the two organizations doesn’t exist. |
404 | authorization_not_found | No non-revoked grant matches the tuple. Already revoked, or never existed. |
Summary
| Operation | Where it happens |
|---|
| Sign LOA | As part of the customer’s verification flow |
| Use the LOA | Set Nxos-On-Behalf-Of: <granter-org-id> on each request |
| List LOAs | GET /v1/authorizations, either side. ?role=authorized for “orgs I can act on”, ?role=granter for “orgs that authorized me” |
| Revoke LOA | POST /v1/authorizations/revoke, by either party |
