Authentication

All requests (except GET /health) require an API key in the X-API-Key header.

Headers

Header	Required	Notes
`X-API-Key`	Always	`sk-nuton-test-…` or `sk-nuton-production-…`
`X-External-User-Id`	For per-user endpoints	Your application’s user identifier — auto-creates a Nuton user on first sight
`X-User-Id`	Alternative to External-User-Id	A Nuton-issued UUID, if you pre-registered the user

User identity — two patterns

Pattern A — Pass-through (recommended)

Send X-External-User-Id: <your-user-id> on every request. Nuton auto-creates a tenant-scoped user record on first sight. No pre-registration needed.

Use whatever identifier makes sense for you (email, UUID, account ID).

Pattern B — Explicit registration

Pre-create users via POST /users. Each gets a Nuton-issued user_id UUID that you then pass via X-User-Id.

Use Pattern B when you need:

Bulk seat provisioning ahead of demand
Per-user metadata stored on Nuton’s side
Strict pre-validation of who’s allowed in

Never embed keys in client code

API keys are bearer credentials. Anyone with the key can make billed calls on your tenant. Always call the Nuton API from a server you control. For client-side apps, mediate through your backend.

Rate limits

Per-tenant rate limits depend on your tier (Starter starts at 60 req/min). Each response includes:

X-RateLimit-Limit — requests-per-minute ceiling
X-RateLimit-Remaining — how many you have left in the current window
X-RateLimit-Reset — Unix epoch when the window resets

When you hit the limit you get HTTP 429 with a Retry-After header. Back off and retry.