Authentication
API keys — how to create, send, scope, rotate, and store them.
Every request authenticates with an API key. Keys belong to one user, and a key can do only what that user can.
Sending your key
Send the key in the X-Api-Key header — or, if your HTTP client prefers it, as a bearer token. Both forms are accepted everywhere.
X-Api-Key: nxd_live_••••••••••••••••
Authorization: Bearer nxd_live_••••••••••••••••Live keys start with nxd_live_. A bearer token that doesn't start with that prefix is treated as a dashboard session, not an API key.
Creating a key
In the dashboard, open your account menu → API keys → Generate key.
- The key is shown once. We store only a hash, so it can't be shown again — copy it straight into your secret store.
- Generating a new key revokes your current active key by default. That makes rotation a single step, but plan for it: anything still using the old key stops working.
Scopes
A key can be limited to specific permissions. A scoped key can never do more than its user can. A key with no scopes has its user's full access.
| Scope | Allows |
|---|---|
agents.run | Everything under Agents, Automation, Data, and Live Search: running agents, groups, and pipelines, managing your groups and pipelines, reading run history, and previewing, querying, exporting, and downloading data. |
For an integration that starts runs and collects data, agents.run is all you need. Other scope names exist for staff and account administration; they don't unlock anything in these docs.
Some endpoints need only a valid key
Schedules and managing your keys check who you are, not which scopes the key has. A key scoped to agents.run can still use them.
Revocation and rotation
Revoke a key from the same API keys screen. Revoked keys stop working immediately.
To rotate without downtime:
- Generate a new key (this revokes the old one).
- Update your secret store and redeploy.
Because generating revokes the previous key, do this during a deploy you control.
Managing keys over the API
The same operations are available to automation. Each acts on the keys of the user the calling key belongs to.
| Endpoint | Does |
|---|---|
GET /api/api-keys | Your keys: keyPrefix, name, scopes, isActive, isRevoked, createdDate, expires, and lastUsedDate. The full key is never returned again. |
POST /api/api-keys | Generate a key: { "name": "billing-sync", "scopes": ["agents.run"] }. Both fields are optional. The response's key is the only time you see it. |
DELETE /api/api-keys/{id} | Revoke a key. |
Generating a key revokes the active one — including the key you called with
POST /api/api-keys revokes your current active key. If you call it with that key, the call succeeds, and every later request with the old key returns 401. Store the new key from the response before you do anything else.
lastUsedDate tells you whether a key is still in use before you revoke it. Unrecognised scope names are dropped; if none are left, the key gets full access.
Storing keys safely
Never ship a key to a browser or a mobile app
API keys are server-side credentials. Anything in client-side code, a mobile bundle, or a public repository can be extracted. Call NexqData from your own backend, and keep the key there.
- Keep keys in environment variables or a secret manager — never in source code.
- Give each integration its own user and key, so revoking one doesn't break the others.
- Use the narrowest scope that works.
NEXQDATA_API_KEY=nxd_live_••••••••••••••••401 vs 403
| Status | Meaning | What to do |
|---|---|---|
401 Unauthorized | The key is missing, malformed, or revoked. | Check the header name and the key. |
403 Forbidden | The key is valid, but it — or its user — doesn't have the permission the endpoint requires. | Check the key's scopes and the user's role. |
See Errors for the full list.