Authentication

Base URL

https://sandbox-api.nuez.app/v1

nuez is currently only available in this sandbox environment — see current status.

Get a JWT

Unlike MCP, the REST API does not accept a raw API key directly — exchange it for a JWT first:

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

{ "token": "eyJhbGciOi...", "expires_in": 86400 }

Or, for a human logging in with a password instead of an agent using a key:

curl -X POST https://sandbox-api.nuez.app/v1/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "..."}'

Both return the same {token, expires_in} shape. expires_in is seconds, controlled by JWT_EXPIRY_HOURS server-side (default 24h). There’s no refresh endpoint — request a new token the same way once the old one expires.

Bearer token

Include the JWT as a Bearer token in every REST request:

curl https://sandbox-api.nuez.app/v1/balance \
  -H "Authorization: Bearer eyJhbGciOi..."

Key format

nz_<24 random bytes, base64url>

There’s no nz_sk_live_/nz_sk_test_ distinction and no scopes — see API keys for the full model.

Error responses

Every endpoint returns errors in a consistent shape:

{ "error": "CODE", "message": "human-readable description" }

Status	Code	Meaning
`400`	`INVALID_JSON`	Malformed request body
`401`	`UNAUTHENTICATED`	Missing Bearer token
`401`	`TOKEN_EXPIRED`	JWT expired
`401`	`INVALID_TOKEN`	JWT signature/claims invalid
`401`	`INVALID_API_KEY`	Wrong key at `/v1/auth/token`
`401`	`INVALID_CREDENTIALS`	Wrong email/password at `/v1/login`
`429`	`RATE_LIMIT_EXCEEDED`	Over 60 requests/minute for this user