Authentication & Limits
How keys work, what happens when you revoke one, how much you can call, and what every error means.
Sending the key
Every request carries the key in an X-Api-Key header. There is no OAuth flow, no token exchange and no expiry to refresh — the key is the credential.
X-Api-Key: scored_a1b2c3d4...A missing or unrecognised key is 401. There is no anonymous access to any endpoint.
Managing keys
All keys for your organisation are listed under Settings → Integrations, each showing its name, the first few characters, when it was created and when it was last used. The last-used time is the quickest way to find a key nothing is calling any more.
Create one key per integration rather than sharing a single key everywhere. It costs nothing, and it means revoking a compromised key does not take down everything else you have built.
Revoking a key
Click Revoke next to the key. Revocation is permanent — a revoked key can never be reactivated, and the raw value cannot be recovered to reuse.
Revocation takes up to 60 seconds
Verified keys are cached briefly so ordinary traffic does not hit the database on every call. A revoked key can therefore keep working for up to a minute before it starts returning 401. Plan for that minute if you are revoking a key because it leaked.
Rate limits
Each key may make 100 requests per minute. The limit is per key, so separate integrations do not compete with each other. Going over returns 429, and the response carries the standard rate-limit headers so you can see your remaining allowance and when the window resets.
If you are building a public page, cache responses on your side rather than calling per visitor. League data changes when a match is scored, not on every page load — a minute of caching is usually invisible to readers and removes the limit as a concern entirely.
Plan usage
API calls also count towards your plan's usage allowance. If you exhaust it, requests return 402 with upgradeRequired: true until the allowance resets or the plan changes. This is separate from the per-minute rate limit: 429 means you are calling too fast, 402 means you have used your quota.
Responses and errors
| Status | Meaning | What to do |
|---|---|---|
200 | Success | Read data. |
401 | Key missing, unrecognised or revoked | Check the header, or mint a new key. |
402 | Plan usage exhausted | Wait for the reset or upgrade the plan. |
404 | Unknown UID, malformed UID, or one belonging to another organisation | Check the UID came from this key's own data. |
429 | Over 100 requests in a minute | Back off, or cache on your side. |
500 | Something failed on our side | Retry; if it persists, contact support. |
Note that 404 is deliberately ambiguous. A league that does not exist and a league belonging to somebody else give the identical response, so the API can never be used to probe whether another organisation's data exists.
Keeping a key safe
- Store it as an environment variable or secret, never committed to a repository.
- Use a separate key per integration so one leak does not force a full rotation.
- If a key is exposed in front-end code, treat everything it can read as public — which for this API means your results, fixtures, teams, standings and, if you have enabled it, player names and statistics.
- Revoke keys you no longer recognise. The last-used column tells you which are idle.