Authentication
All /v1 and /scim/v2 requests authenticate with an organization API key sent as a bearer token.
Authorization: Bearer nwk_live_a1b2c3...
Keys are minted from your workspace settings on niah.si
and are scoped to a single organization. The full secret is displayed
once at creation — after that only the key_prefix
is visible. Rotate a key by creating a new one and deleting the old.
Key format
Niah API keys are prefixed with nwk_. Treat the entire string
as a secret; never commit it, log it, or embed it in client-side code.
Make requests from a trusted backend.
Scopes
Every key carries a list of scopes in the form resource:action.
A request is rejected with 403 forbidden_scope if the key lacks
the scope an endpoint requires. Grant the narrowest set each integration needs.
| Scope | Grants |
|---|---|
me:read | Read /v1/me |
consultations:read | List/read consultations and responses |
consultations:write | Create and cancel consultations |
batches:read | List/read batches and results |
batches:write | Create and cancel batches |
panels:read | List panels |
usage:read | Read usage and billing data |
webhooks:read | List webhook configs and deliveries |
webhooks:write | Create/update/delete webhook configs |
automations:read | List/read automations and runs |
automations:write | Create/update/delete automations |
automations:trigger | Trigger automations |
chat.completions | Call /v1/chat/completions |
scim:read / scim:write | SCIM user/group provisioning |
* | Full access (use sparingly) |
Check a key's scopes at runtime via GET /v1/me.
IP allowlists
A key can optionally be restricted to a set of source IPs. Requests from any other address are rejected. Configure the allowlist where you manage the key.
Plan requirements
API access is a paid feature. Keys on the starter plan are
rejected with plan_no_api_access. Your plan also determines your
rate limit.
Auth errors
| Status | Code | Meaning |
|---|---|---|
| 401 | unauthorized | Missing, malformed, or unknown API key |
| 403 | forbidden_scope | Key is valid but lacks the required scope |
| 403 | plan_no_api_access | Organization's plan does not include API access |
| 403 | ip_not_allowed | Source IP is not on the key's allowlist |
/api/code/*)
uses per-user session tokens, and internal service-to-service routes use a
shared secret. Neither is part of the enterprise /v1 API. SCIM
uses the same nwk_ keys with scim:* scopes.