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

# Authentication and concurrency

> Use API-key scopes, idempotency keys, and state versions correctly.

## Authentication

Send your secret as a bearer token:

```http theme={null}
Authorization: Bearer nbq_live_xxx
```

The key identifies the tenant, NBQ, and allowed scopes. Caller-supplied identity headers do not grant access.

## Least-privilege scopes

| Scope                   | Access                                                 |
| ----------------------- | ------------------------------------------------------ |
| `runtime`               | Session runtime routes.                                |
| `configuration:read`    | Read configuration, questions, and compilation status. |
| `configuration:write`   | Read and edit the draft.                               |
| `configuration:publish` | Publish and read configuration audit events.           |

## Idempotency

Every mutating V1 request requires a unique `Idempotency-Key`. Replaying the same key with the same payload returns the same logical result without applying the change twice. Reusing a key for a different payload is rejected.

Keep keys stable when retrying a request after a timeout. Generate a new key for a new business action.

## Optimistic concurrency

Mutations to an existing session include `state_version`. After a successful mutation, replace your stored value with the version returned by the API.

If two workers write from the same version, only one can succeed. On `409 state_version_conflict`, read the session again and decide whether the second action still applies.

<Warning>
  Do not automatically retry a state conflict with a new version without checking the business action. This could apply an obsolete answer to a newer conversation state.
</Warning>