Authentication
Bearer tokens
Section titled “Bearer tokens”All API requests must include a Bearer token in the Authorization header:
Authorization: Bearer sk_live_abc123...Tokens are created from Dashboard > Settings > API Access by workspace owners or admins when the active plan includes API access.
Scopes
Section titled “Scopes”Each token is created with one or more scopes that control access:
| Scope | Endpoints | Notes |
|---|---|---|
metrics:read | /v1/me, /v1/sites, /v1/metrics/*, /v1/usage/* and plan-enabled read endpoints | Endpoint families still depend on the active plan |
usage:read | /v1/usage/* | Usage data only |
A token with metrics:read can always access usage endpoints — you don’t
need a separate usage:read scope. Reports, goals, and tenant endpoints still
depend on the active plan.
GET /v1/me exposes the authoritative runtime product object in product.
GET /v1/sites exposes the current site-level product object in
product_configuration, including collection_profile,
collection_profile_effective_at, and the effective capabilities for that
site. Treat that timestamp as prospective-only: changing the profile does not
backfill older events.
Profile-aware analytics reads also expose an availability object in their
success payload. Extended-only route families still return 409 with
structured availability details when the selected site or period is not
compatible with the required data envelope. Mixed route families keep returning
200: read availability.readModel first to identify the strict-safe
baseline, then availability.sections to flag the enriched slices that remain
locked.
See also: Strict, Extended & Mixed Reports.
Plan-gated route families
Section titled “Plan-gated route families”| Route family | Starter access | Notes |
|---|---|---|
/v1/me | Yes | Always available when the plan includes API access. |
/v1/sites | Yes | Read access to workspace sites. |
/v1/usage/* | Yes | Usage reads stay free of metered units. |
/v1/metrics/* | Yes | Standard timeseries and breakdown reads. |
/v1/reports/* | No | Available only when the active API policy enables these routes. |
/v1/goals* | No | Available only when the active API policy enables these routes. |
/v1/tenants | No | Available only when tenant API access is enabled on the current plan. |
Site allowlist
Section titled “Site allowlist”Tokens can optionally be restricted to specific sites. When an allowlist is configured, the token can only query data for those sites.
If no allowlist is set, the token can access all sites in the workspace.
Tenant allowlist
Section titled “Tenant allowlist”Tokens can also be restricted to specific tenants through allowedTenantIds
when the active plan allows tenant API access.
When a tenant allowlist is configured, pass tenant_id on analytics requests
and use GET /v1/tenants to list the accessible tenants for a site_id.
Tenant allowlists are enforced against the stable tenant_id, not the routing
slug.
See also: Multi-tenant analytics and the Multi-tenant guide.
Token security
Section titled “Token security”- Token secrets are shown only once when created — store them securely
- Tokens are hashed server-side and cannot be recovered
- Revocation takes effect immediately on all subsequent requests
- Each request is validated against DynamoDB — there is no token cache
Request headers
Section titled “Request headers”| Header | Required | Description |
|---|---|---|
Authorization | Yes | Bearer sk_live_... |
X-Request-Id | Recommended | Client-generated request ID for debugging and support |
Rate limiting
Section titled “Rate limiting”Requests are rate-limited per token in 60-second sliding windows. Limits vary by plan (see Limits & pricing).
When rate-limited, the API returns 429 with these headers:
| Header | Description |
|---|---|
X-RateLimit-Limit | Max requests in the current window |
X-RateLimit-Remaining | Remaining requests (0 when limited) |
X-RateLimit-Reset | Unix timestamp when the window resets |