Authentication

All API requests require a Bearer token in the Authorization header.

Authorization: Bearer atb_live_your_key_here

Getting a key

Create API keys from Settings > Developer in the Atribu dashboard. Each key is scoped to a single profile.

Scopes

Each API key has granular scopes that control what data it can access.

Analytics (read-only)

PII (read-only)

Commerce (read-only)

Conversion export (read, write)

Provisioning (write)

Attribution & goals (write)

Calendar (read, write, manage)

Messaging (write)

Messaging (read-only)

Inbox conversations (read, write)

Default scopes when creating a key: analytics:read, campaigns:read, conversions:read, realtime:read.

The MCP user token — one credential for both surfaces

Since #1084 an MCP user token (atb_user_…) authenticates on /api/v1 exactly as it does on mcp.atribu.app. It is the credential for a person's own AI agent: one token, both surfaces, no separate API key to mint per profile.

Authorization: Bearer atb_user_your_token_here

How to get one

How it differs from an API key

An API key is a tenant — it is minted for exactly one profile. A user token names a person, who may reach several. So:

• ?profile_id=<uuid> is required on profile-scoped routes. Its absence is a 400 invalid_request, never a guess. Workspace-scoped routes take ?workspace_id= (or the path segment) instead.
• A profile the person cannot reach answers 404 not_found — byte-identical to a profile that does not exist, so the status line can never be used to enumerate tenants.
• The workspace-grain routes an API key is refused on (/api/v1/workspaces, the cross-profile leaderboards) are open to a user token.

What the MCP scopes map to

A request's scopes are the intersection of two things: what the token's mcp:* grant maps to, and what the person's own workspace/profile membership already grants. Neither can widen the other.

No MCP scope grants commerce:read, exports:read, exports:write, visitors:read, events:write, creatives:write, or any messaging, calendar or inbox scope. Those need an API key.

Because the answer is an intersection, a 403 insufficient_scope can mean either half is too narrow — the message names both, so you know whether to re-consent with a wider grant or ask a workspace admin for more access.

Routes a user token can never reach

Three groups of writes answer 403 insufficient_scope to a user token whatever its grant, because acting on them would let a credential administer the credential system itself. Widening the token's scopes does not change the answer; only a signed-in session (or, where it already worked, HTTP Basic) can do these.

Rate limits and revocation

A user token is metered against its own rate_limit_units_per_minute, in a bucket separate from both API keys and browser sessions — so an agent's loop cannot rate-limit its owner's dashboard, nor the reverse. A revoked or expired token answers 401 with the same envelope a revoked API key gets. Revoke one from Settings > Developer, or disconnect the OAuth client that holds it.

Rate limits

Default: 60 requests per minute per key.

Heavy endpoints (customers, visitors, journey detail) cost 3x — meaning they consume 3 units of your rate limit per call.

Endpoints with their own bucket

A few endpoints carry a sustained cap on top of the per-minute limit, because one call is far more work than a read. These buckets are separate from your per-minute allowance — they can neither consume it nor be consumed by it — and a 429 from one carries Retry-After.

When rate limited, you'll get a 429 response with a Retry-After header (seconds).

Key rotation

Rotate keys with zero downtime:

Security best practices

• Use the minimum scopes needed — don't grant customers:read if you only need analytics
• Rotate keys regularly — the rotation endpoint makes this seamless
• Revoke compromised keys immediately — revocation is instant

Error responses

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or expired API key",
    "status": 401,
    "request_id": "req_a1b2c3d4"
  }
}

Related