curl --request POST \
--url https://api.usenexio.com/api/v1/environments \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"slug": "dev",
"name": "Development"
}
'import requests
url = "https://api.usenexio.com/api/v1/environments"
payload = {
"slug": "dev",
"name": "Development"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({slug: 'dev', name: 'Development'})
};
fetch('https://api.usenexio.com/api/v1/environments', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"slug": "dev",
"kind": "live",
"created_at": "2023-11-07T05:31:56Z",
"name": "Development"
}Create environment
Create a sandbox environment in your org.
curl --request POST \
--url https://api.usenexio.com/api/v1/environments \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"slug": "dev",
"name": "Development"
}
'import requests
url = "https://api.usenexio.com/api/v1/environments"
payload = {
"slug": "dev",
"name": "Development"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({slug: 'dev', name: 'Development'})
};
fetch('https://api.usenexio.com/api/v1/environments', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"slug": "dev",
"kind": "live",
"created_at": "2023-11-07T05:31:56Z",
"name": "Development"
}Behavior
- Accepts organization keys only. A scoped key gets
403 insufficient_capability. - Creates an environment of kind
sandbox. Theliveenvironment exists already and cannot be created. - The slug must match
^[a-z0-9_]{1,16}$and must not be one oflive,test,internal,admin,api,nexio,draft,all. It cannot change later. - An org can have at most 5 sandboxes. The sixth gets
400 environment_limit_reached. - The body is at most 4 KiB and accepts only
slugandname.
Authorizations
Send the key as Authorization: Bearer <key>. Two kinds of key exist.
Organization keys are issued in the portal (Settings, then API keys),
each bound to one environment, shaped nx_<environment slug>_<64 hex>. They carry
no capabilities and pass every capability check, with one exception:
routes under /records, /actions, /operations,
/api/v1/engines/{id}/opportunities, /api/v1/graph and
/api/v1/catalog/documents accept an
organization key only when its environment is live, and refuse any
other with 403 scoped_key_required. Revocation takes effect within 60
seconds.
Scoped keys are issued by Nexio on request, shaped
nxsk_v1_<24 hex key id>_<43 character secret>. Each is bound to one
org, one environment, a set of engines and a set of capabilities. A
malformed, unknown or revoked nxsk_ key fails with 401 and is never
retried as an organization key. Revocation takes effect on the next
request. A scoped key without a route's capability gets 403
insufficient_capability; a scoped key not bound to the engine gets 403
engine_binding_forbidden.
Key-grantable capabilities: engines:read, runs:write, runs:read,
runs:defensibility:read, runs:test, catalog:read,
catalog:documents:read, webhooks:manage, conversations:use,
conversations:export, records:read, records:opportunities:run,
actions:write, actions:read, graph:read, records:analyze.
Routes that accept organization keys only (every scoped key gets 403
insufficient_capability): environment management, engine create,
update, configuration and publish, and conversation instance
authoring. Each operation description names the capability a scoped
key needs.
Body
Response
Environment created.
Immutable routing identifier. live for the live environment.
^[a-z0-9_]{1,16}$"dev"
live, sandbox UTC, second precision, for example 2026-09-23T15:10:42Z.
Optional display label. The only field that can change after creation. Omitted when no name is set.
64"Development"