Authentication

Bearer tokens, workspace scoping, ability narrowing and rate limits.

2 min read

Every request is authenticated with a bearer token issued from Settings → API tokens.

The header

http

Authorization: Bearer nxs_xxxx_yyyyyyyyyyyyyyyy
X-Tenant-Slug: your-workspace
Accept: application/json

X-Tenant-Slug is required when several workspaces share a hostname. On a dedicated subdomain the workspace comes from the host and the header is optional.

A token belongs to a membership, not a user

A token identifies one person in one workspace. Somebody who belongs to three workspaces needs three tokens, and a token issued for workspace A can never read workspace B.

This is deliberate. A token bound only to a user account would be valid everywhere that user has access — so a consultant issuing an integration credential for one client would be handing out access to all of them.

Abilities narrow, never widen

At issue time you pick the token's abilities from the permissions its membership already holds.

The intersection is applied on every request. A token scoped to leads.view authorises exactly that, even when the membership behind it belongs to an owner whose own permission check would otherwise short-circuit to true.

An empty ability list means "everything this membership can do". Prefer an explicit list — it is the difference between a leaked key reading one endpoint and a leaked key doing anything.

Storage

The plaintext token is shown once, at issue. Only a SHA-256 hash is stored, so it genuinely cannot be recovered — issue a new one and revoke the old.

A short token_prefix is retained so you can identify a token in a list without the secret being retrievable.

Restricting by source address

A token can carry an allow-list of IPs. A request from anywhere else is rejected even when the token is correct. Worth setting for server-to-server integrations, which have a stable address; not worth it for anything running on a laptop.

Rate limits

Applied per token and reported on every response:

http

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 594
X-RateLimit-Reset: 1753804800

A 429 carries Retry-After in seconds. Respect it — retrying immediately cannot succeed and still counts against you.

Revoking

Settings → API tokens → Revoke. It takes effect on the next request.

Revoked tokens are retained rather than deleted, because last_used_at and last_used_ip are exactly what an incident review needs.

Stuck on a response you did not expect? Send us the request_id from the error body and we can trace the exact call — contact support.