API keys

Key format

nz_<24 random bytes, base64url>

There is no nz_sk_live_/nz_sk_test_ distinction and no scopes — a key is either valid for a user or it isn’t. Which environment it works against depends entirely on which base URL you call (https://sandbox-api.nuez.app is the only environment currently available).

Two ways to use a key

Surface	How the key is used
MCP (`POST /mcp`)	Pass the raw key directly as `Authorization: Bearer nz_...`. The handler detects the `nz_` prefix and looks it up by hash — no exchange needed.
REST API (`/v1/*`)	Exchange it once for a JWT via `POST /v1/auth/token`, then use `Authorization: Bearer <jwt>` for every REST call. JWTs expire after `JWT_EXPIRY_HOURS` (default 24h).

curl -X POST https://sandbox-api.nuez.app/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"api_key": "nz_YOUR_KEY_HERE"}'
# → {"token": "eyJ...", "expires_in": 86400}

POST /v1/login (email + password) is the alternative way to get a JWT — for a human logging into the dashboard rather than an agent.

One key per agent

Every API key belongs to a single user but you can create as many as you want — one per agent is the recommended pattern:

Independent revocation — DELETE /v1/api-keys/{id} kills one agent’s access without affecting others
Per-agent audit trail — every payout attempt records the api_key_id and api_key_name that created it, and that identifier is echoed in outgoing webhook payloads

There is no per-key policy — threshold, whitelist, and every other policy rule are configured per user (GET/PUT /v1/thresholds) and apply identically no matter which of the user’s keys made the call. See Policy engine.

Creating a key

curl -X POST https://sandbox-api.nuez.app/v1/api-keys \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{"name": "claude-supplier-agent"}'

{
  "id": "6f2c...",
  "name": "claude-supplier-agent",
  "key": "nz_...",
  "created_at": "2026-07-18T14:32:00Z"
}

Note that a user’s very first key is created automatically at signup (POST /v1/users returns it as default_api_key) so an agent can start calling MCP tools before you’ve created a dedicated key.

Listing and revoking

curl https://sandbox-api.nuez.app/v1/api-keys -H "Authorization: Bearer <jwt>"
# → {"api_keys": [{"id": "...", "name": "...", "created_at": "..."}]}

curl -X DELETE https://sandbox-api.nuez.app/v1/api-keys/{id} -H "Authorization: Bearer <jwt>"
# → 204 No Content

After deletion, requests with that key return 401 unauthorized (MCP) or fail the JWT exchange (REST). Other keys on the same user are unaffected.