> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usenexio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication and scoped credentials

> Environment-bound bearer credentials and least-privilege capabilities.

All `/api/v1/*` requests require a bearer credential:

```http theme={null}
Authorization: Bearer nxsk_v1_<public-id>_<secret>
```

`nxsk_` is the exclusive namespace for scoped partner credentials. A malformed,
unknown, rotated, revoked, or unsupported `nxsk_` value returns `401` and is
never retried against the grandfathered legacy-key store.

Each scoped key is bound at issuance to exactly one organization, one canonical
named environment, a set of engine IDs, and a capability set. Those bindings
come from the authenticated principal. Request bodies and query parameters
cannot select another organization or environment.

## Capabilities

| Capability                | Permitted partner surface                                                                                          |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `runs:write`              | Submit runs and write supported run-family signals for bound engines.                                              |
| `runs:read`               | Poll runs for bound engines in the key's environment.                                                              |
| `engines:read`            | List bound engines and discover their released versions.                                                           |
| `catalog:read`            | Read the organization's current served carrier and product catalog.                                                |
| `webhooks:manage`         | Create, update, rotate, inspect, and resend webhooks in the key's environment.                                     |
| `runs:defensibility:read` | Read restricted defensibility packets for bound runs. This is separate from ordinary `runs:read`.                  |
| `runs:test`               | Select deterministic `test_scenario` fixtures in a sandbox. This does not grant ordinary run submission by itself. |

A runtime key normally carries `runs:write`, `runs:read`, `engines:read`, and `catalog:read`.
A webhook-admin key carries `webhooks:manage`. Grant `runs:test` and
`runs:defensibility:read` only to principals that need those separate surfaces.
Missing grants return `403` with `code: insufficient_capability`.

Keys are returned only at issuance or rotation. Store them in a server-side
secret manager. Never place them in browser code, logs, URLs, or repositories.

## Authentication errors

```json theme={null}
{
  "code": "unauthorized",
  "message": "Missing or invalid API key"
}
```

If credential lookup is temporarily unavailable, the API returns `503` with
`code: auth_unavailable`.

Grandfathered `nx_live_...` and `nx_test_...` credentials retain broad access
during the compatibility window. New partner integrations should use scoped
`nxsk_v1_...` credentials.