Authentication
Every request must carry a valid API key. Keys are issued through the dashboard after signup. There is no anonymous tier.
Signup
Sign up at /signup with one of:
- Magic link (email only, no password)
- GitHub OAuth
- Google OAuth
- X (Twitter) OAuth
All paths produce a verified email. A live API key is created on first login and is visible at /dashboard/keys.
Key format
Every key issued today starts with the bbs_live_ prefix, followed by a random alphanumeric string:
bbs_live_a1B2c3D4e5F6...There is no separate sandbox/test key today — every key is live traffic against real quota from the moment it's created. (A bbs_test_ prefix exists in older client code as a placeholder for a future sandbox tier, but the API rejects an explicit request for one today rather than silently minting a live key under a different name.)
Sending the key
Two equivalent transports, pick one:
curl https://api.bigballsdata.com/v1/sports \
-H "Authorization: Bearer bbs_live_a1b2c3d4e5f6..."curl https://api.bigballsdata.com/v1/sports \
-H "x-api-key: bbs_live_a1b2c3d4e5f6..."Failure modes
Both 401 cases below share the same error.code — the error.message is what tells them apart. See the full error codes reference for every code the gateway emits.
| Status | Code | Message | Cause |
|---|---|---|---|
| 401 | unauthorized | missing API key | No Authorization or x-api-key header sent |
| 401 | unauthorized | invalid API key | Key not recognised or revoked |
| 403 | forbidden | (varies) | Endpoint above the key's plan tier |
Rotating a key
From the dashboard, /dashboard/keys → Rotate. The new key is shown once; the old key keeps working for a 60-second grace window so deploys can roll without breakage. After 60 seconds the old key returns 401 unauthorized ("invalid API key").
Scopes
Keys are issued with full scope by default. Per-scope key restriction (read-only, sport-restricted, IP-allowlisted) is on the roadmap and not configurable today.