API authentication

The REST API (Scale plan) authenticates with bearer tokens you create per use-case, scoped, revocable, and never able to read account or billing data.

• Key takeaways
• Bearer tokens, created per consumer, scoped read-only or +goal-management, shown once.
• 600 req/min per token with standard 429 + Retry-After.
• Tokens never expose account, billing, or settings data.

Creating a token

1. Go to Settings → API and click New token.
2. Name it after its consumer, “Looker import”, “Internal wiki widget”.
3. Choose scope: read-only stats (default) or stats + goal management.
4. Copy it once, tokens are shown a single time and stored hashed.

Using it

curl https://api.bobray.com/v1/stats?site=br_7fk2mq&period=30d \
  -H "Authorization: Bearer YOUR_TOKEN"

Limits and hygiene

• Rate limit: 600 requests/minute per token, with standard 429 + Retry-After behavior.
• Tokens can be revoked instantly; revocation propagates within seconds.
• Keep tokens server-side. If one must ship to a browser, use a read-only scope and treat the data as public.

Common pitfalls

The mistakes we see most often on this topic, so you can skip them entirely.

• Reusing one token everywhere; revoking for one integration then kills all.
• Committing tokens to a repo, treat them like passwords.
• Shipping a write-scoped token to a browser 'for now'.

Quick reference