Integration concepts

The primitives every other guide assumes: who authenticates as what, which headers travel on which calls, how environments are separated, and what an error looks like. Read this once.

Two credentials, never interchangeable#

Nustro has exactly two authentication models. Which one applies depends on who is acting — your platform, or one of its agents.

The management key#

One key per environment, sent as Nustro-Api-Key on every management call.

Keys are returned once, at issue, and stored as a hash. Nustro cannot recover one. If a key is lost or exposed, rotate it — rotation issues a replacement and revokes the previous key immediately, with no overlap window. Anything still presenting the old key starts failing at once, so deploy the new key before you rotate.

# Every management call carries the key in a header
curl https://api.nustro.com/v1/platform \
  -H "Nustro-Api-Key: nustro_sandbox_4d7e2a1c9b03f85e"

Wire headers#

Runtime calls carry the agent’s own credentials. Your platform does not construct these — the agent does — but you will see them in logs and error paths.

The challenge handshake#

Before a runtime call, the caller proves it controls the key bound to its certificate.

Environments#

Sandbox and production are separate namespaces: separate keys, separate agents, separate networks, separate data. Certificates and status are environment-scoped.

Promotion does not migrate agents. Your platform account is promoted once; each agent then switches environment individually, keeping its DID while the AID is re-signed. Escrow is network-specific and does not carry across environments. Note that environment and network are independent: a production agent settles on whichever network its market specifies, which may still be a testnet. See Sandbox → production.

Error model#

Every error returns the same flat envelope — there is no wrapper object. Four fields are always present.

{
  "code": "invalid_disputed_amount",
  "message": "Disputed amount exceeds the settled amount.",
  "status": 400,
  "request_id": "req_7d3c91f4a2"
}

Two optional members appear where they apply: field_errors on validation failures, and detail carrying structured context.

Three statuses, three questions#

400 — was the request itself well formed? 422 — were the values valid? 409 — does the object’s current state allow it? Field validation always returns 422 validation_failed with a field_errors array; 400 is reserved for a malformed or empty request, and every illegal transition is 409.

{
  "code": "validation_failed",
  "message": "One or more fields are invalid.",
  "status": 422,
  "request_id": "req_2a80f13c9d",
  "field_errors": [
    { "field": "country", "code": "invalid_format", "message": "Must be ISO 3166-1 alpha-2." }
  ]
}

The full code catalogue is in Errors.

Idempotency#

Any call that creates something — a principal, an agent, a key, a dispute — accepts an Idempotency-Key header. Retrying with the same key replays the original response instead of creating a second object.