Skip to main content
Every call to /api/v1/ carries one API key in the Authorization header. The key decides which organization (org) and which environment the request belongs to.
The only unauthenticated routes are GET /health, GET /robots.txt and the inbound event route POST /api/v1/events/ingest/{source_key}, which is authenticated per source instead: an HMAC signature, or, for an ams360_ons source, a shared authentication code (see Inbound events).

​
Two kinds of API key

The prefix nxsk_ always means a scoped key. A malformed, unknown or revoked nxsk_ key is refused with 401 and is never tried as an organization key.
Organization keys are the keys the portal issues. Nexio’s error messages sometimes call them “legacy org keys”. They are fully supported.

​
Create an organization key

  1. Open Settings, then API keys in the portal. You need the admin or developer role.
  2. Choose Create API Key, give the key a name, and pick an environment.
  3. Copy the key. The portal shows it once; later requests are verified against a hash of it.
The list shows each active key’s name, environment, prefix, creation time and last use. Rename changes only the label. Revoke stops the key within 60 seconds. Keys created in the portal do not expire.

​
Get a scoped key

Ask Nexio for a scoped key when you want least privilege: a key that can, for example, only read records through Records (records:read). Say which environment and which capabilities it needs. Nexio records every issue, grant change and revocation in your org’s access audit log. There is no portal page or API for scoped keys.

​
Capabilities

A capability is one permission a scoped key carries. An organization key carries no capabilities and passes every capability check, except where the tables below say otherwise. The three records:* names share the /api/v1/records route prefix. records:read gates the Records reads, including the generic family read; the action ledger reads take actions:read and the analyses reads take records:analyze. The earlier prefix /api/v1/book, the book: capabilities and the X-Nexio-Book-* headers keep working as aliases. A scoped key without the capability a route needs gets 403 insufficient_capability. Five more names exist only inside the portal and can never be put on a key: engines:manage, instances:manage, environments:manage, connections:manage and runs:trace. The public routes that need engines:manage, instances:manage or environments:manage accept organization keys only (below). connections:manage and runs:trace gate portal pages only. In the portal, these names follow from a person’s role permissions: for example, a role with the engines:manage permission may author both engines and conversation instances (instances:manage). See Team and roles.

​
Engine binding

A scoped key lists the engines it may use. In the API reference, every route that accepts a scoped key and has an engine slug or a run ID in its path checks that the engine is in the list; if it is not, the answer is 403 engine_binding_forbidden. A scoped key bound to no engines cannot call those routes. GET /api/v1/engines returns only the engines the key is bound to.

​
Routes that accept only organization keys

These routes refuse every scoped key with 403 insufficient_capability, whatever capabilities it holds. Use an organization key, or do the work in the portal. Routes that serve Nexio-hosted applications refuse scoped keys the same way. One of them is the app data store (Application records), which also refuses organization keys from environments other than live.

​
Routes that need a live key or a scoped key

On these families an organization key is accepted only if it was created for the live environment. An organization key from any other environment gets:
with status 403. A scoped key from any environment passes this check and then needs the capability.

​
Acting for a person

The key proves the org. When your server acts for a specific person in that org, send that person’s stable user ID from your identity provider in X-Nexio-Acting-Principal, and on Records routes their verified sign-in email in X-Nexio-Acting-Email. Nexio does not issue user IDs to your end users. Always send the stable ID, never the email, in X-Nexio-Acting-Principal.
  • The header can only narrow what the key already allows. What the person may reach comes from your own systems; see Access plane.
  • On Records reads, the person’s own authority decides which records come back. See Authority and scope for the related identity headers and the signed assertion.
  • On a run, the acting principal is recorded as who submitted it and is part of the idempotency scope. A run of a matching engine without it answers 400 run_requires_acting_principal. A body submitted_by is accepted only alongside the header and equal to it; without the header, or with a different value, the answer is 400 acting_principal_mismatch.
Send these headers only from your server. The API sends no CORS headers, so browsers cannot call it directly.

​
Errors

Authentication runs before rate limiting, so a bad key gets 401, never 429. See the error reference for every code.

​
Next

Environments

Keep sandbox traffic apart from live traffic.

Requests and errors

Headers, status codes and retries.
Last modified on September 25, 2026