Get started
Authentication
Every private endpoint requires an API key. Pick one header per request — Bearer is recommended.
Authentication headers
Recommended
Authorization: Bearer <API_KEY>Alternative
X-Api-Key: <API_KEY>curl "https://api.betspread.io/api/v1/sports" \
-H "Authorization: Bearer $BETSPREAD_API_KEY"curl "https://api.betspread.io/api/v1/sports" \
-H "X-Api-Key: $BETSPREAD_API_KEY"Where to get the key
Keys are created in the dashboard under API keys. The full secret is shown once at creation; store it in a secret manager and reference it through an environment variable.
Key rotation
Rotate keys from the same dashboard view. We recommend creating the new key, deploying it to your environment, then revoking the old key to avoid downtime. Revoked keys return 401 invalid_api_key on the next request.
Key scopes
API key scopes are restrictive only. Existing keys and the default creation mode are unrestricted, so current integrations keep the same organization-level access unless you intentionally create a restricted key.
Restricted keys do not grant plan, Live, History, sport, or bookmaker access that the organization does not already have. Organization plan limits and bookmaker entitlements remain the outer authority; a key scope can only narrow what that key may request.
v1 scopes cover product channels (REST, Live, History), bookmakers, and sports. In v1, league, market type, environment, and event phase are deferred until those public contracts are stable. A request outside the key's allowed scope returns 403 api_key_scope_denied.
Failure modes
Missing keys return 401 missing_api_key, rejected keys return 401 invalid_api_key, missing entitlements return 403 forbidden, and a live request without a Live plan returns 403 live_not_enabled. A restricted key used outside its product-channel, bookmaker, or sport scope returns 403 api_key_scope_denied. See Errors for the full contract.