Authentication
API key setup, scopes, rate limits, and security best practices
All API requests require a Bearer token in the Authorization header.
Authorization: Bearer atb_live_your_key_hereGetting a key
Create API keys from Settings > Developer in the Atribu dashboard. Each key is scoped to a single profile.
Show once
Keys are shown exactly once at creation. Store them securely — you cannot retrieve them later.
Scopes
Each API key has granular scopes that control what data it can access.
| Scope | Access |
|---|---|
analytics:read | Overview, timeseries, breakdowns (channels, pages, countries, devices, browsers, OS, referrers), quality, keywords |
campaigns:read | Campaign performance, ROAS, ad set/ad breakdowns, daily trends |
conversions:read | Conversion counts, daily conversion timeseries, revenue, cash collected |
customers:read | Customer list with PII (name, email), individual journey timelines |
visitors:read | Visitor list with PII (name, email), session history |
realtime:read | Live visitor count |
Default scopes when creating a key: analytics:read, campaigns:read, conversions:read, realtime:read.
PII scopes
customers:read and visitors:read expose personal data (names, emails, journey details). Only grant these when your integration specifically needs customer-level data.
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.
| Header | Description |
|---|---|
X-RateLimit-Limit | Your total limit per minute |
X-RateLimit-Remaining | Remaining requests in current window |
X-Request-Id | Unique request ID for debugging |
When rate limited, you'll get a 429 response with a Retry-After header (seconds).
Key rotation
Rotate keys with zero downtime:
Call the Rotate endpoint — creates a new key
Both old and new keys work for 48 hours
Update your integration with the new key
The old key automatically expires after the grace period
Security best practices
Server-to-server only
This is a server-to-server API. Never expose keys in client-side JavaScript, mobile apps, or browser code.
- Use the minimum scopes needed — don't grant
customers:readif 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"
}
}| Code | Status | Meaning |
|---|---|---|
unauthorized | 401 | Missing or invalid API key |
insufficient_scope | 403 | Key doesn't have the required scope |
rate_limit_exceeded | 429 | Too many requests |
invalid_parameter | 400 | Bad query parameter |
invalid_date_range | 400 | Date range exceeds 366 days or dates are invalid |
internal_error | 500 | Server error — include the request_id when reporting |