Authentication

Every request to a /v1/* endpoint must carry an API key. This page covers how to send one, where to store one, and how to rotate them safely.

Key formats

Prefix	Environment	Base URL
sk_live_...	Production	https://api.scorelytics.pro
sk_test_...	Staging	https://staging-api.scorelytics.pro

Keys are 32 random bytes encoded as base62 — they have no internal structure and the prefix is only a hint to humans.

Three ways to send the key

The API accepts the key in three transports. Pick whichever fits the channel you control.

1. Header (recommended)

GET /v1/football/matches HTTP/1.1
Host: api.scorelytics.pro
X-API-Key: sk_live_a1b2c3d4...

2. Bearer token

Useful when the calling library expects a standard Authorization header (e.g. OAuth-aware HTTP clients).

Authorization: Bearer sk_live_a1b2c3d4...

3. Query parameter

Use only when headers are not an option — in particular for WebSocket connections, where browser APIs do not let you set headers.

wss://api.scorelytics.pro/v1/ws/live?api_key=sk_live_a1b2c3d4...

Query parameters leak

Query strings show up in proxy logs and browser history. Prefer the header in every server-to-server call. Use the query form only when the protocol forces it.

Scopes

Each key has a set of scopes that gate what it can read.

Scope	Grants
read:matches	Match list, detail, events, stats, lineups, standings, H2H.
read:leagues	League list and current standings.
stream:websocket	WebSocket connections.
mcp:invoke	MCP server tool calls.

Default keys carry all read scopes. Restrict them in the dashboard if you ship the key to an untrusted environment (e.g. a mobile app).

Storage

• Server side — environment variables or a secret manager (AWS Secrets Manager, Vault, Doppler, 1Password). Never check keys into git.
• Edge / browser — proxy through your backend. Never put a production key in browser JavaScript; assume any key shipped to a client is public.

A common pattern is to mint short-lived, scope-limited derived tokens for edge use cases. Reach out to support@scorelytics.pro if you need this.

Rotation

Rotate keys on a fixed cadence (we recommend every 90 days) and immediately when:

• A laptop with the key is lost or compromised.
• A team member with key access leaves.
• A log file containing the key is exposed.

In the dashboard, Settings → API keys:

1. Click Create key to provision a new key.
2. Roll the new key out to your services.
3. Once metrics confirm zero traffic on the old key, click Revoke.

Revocation is immediate. Any in-flight request using a revoked key returns 401.

Verifying a key

Send a GET /health — it doesn't require auth — to confirm reachability, then GET /v1/football/leagues to confirm the key works:

curl -i https://api.scorelytics.pro/v1/football/leagues \
  -H "X-API-Key: sk_live_..."

A 200 confirms the key is valid and has the read:leagues scope.

Errors

Symptom	Cause	Fix
401 missing or invalid api key	Key absent, malformed or revoked.	Verify the key value and the header name.
401 only on certain endpoints	Scope missing on the key.	Re-issue with broader scopes or use a different key.
429 Too Many Requests	You're hitting a rate limit.	See Rate Limits.

See the full taxonomy on the Errors page.