API keys, scopes and rate limits

Access to an odds feed is more than a URL and a token. How keys are shaped, what a scope limits, and how rate limits and caching behave decide how cleanly the feed fits your code.

This guide covers the OddsRelay access contract at the level you need to plan an integration. Every parameter is in the API docs.

What a key looks like

OddsRelay keys are prefixed so you always know what you are holding: or_live_ for a server key, or_pub_ for a browser key that only answers calls from its own websites. You send the key as a Bearer token in the Authorization header or as x-api-key, never in a query string, never in a URL.

Keys are stored hashed, so the raw secret is shown exactly once, when it is made. If a key leaks, you roll it: the new key works at once and the old one keeps working for 24 hours, so revoke it straight away. Treat a key like any other production secret.

What a key can reach

Every plan gets every feed type and bookmaker its region serves. A key can be narrowed below that, so a service that reads only one feed holds a key that reads only that feed.

A call outside the key's scope is refused with a 403 that names the axis, and a refusal costs nothing.

• Feed types: the six matched feeds and raw.
• Region: the region the call names in region=, one per call.

Tokens and the rate limit

Each account has a monthly allowance of tokens. A call's price comes from the feed and the filters you send, never from the size of the reply, and quote=true prices any request for free before you make it.

Each account also has a rate limit, a cap on requests per 10 seconds and per minute, the same on every plan. The way to stay under both is to make each request cheaper.

Cheap polling with ETag and 304

Data replies carry an ETag (a free quote never does). Send it back as If-None-Match on your next request and, if nothing has changed, you get a 304 Not Modified with no body, which costs no tokens and still counts towards the rate limit.

With gzip, this means you can poll at your own pace without re-downloading a reply you already hold.

Step by step

1. Get a key Sign up free, then create an or_live_ server key in your dashboard. Store it as a secret. It is shown once.

2. Scope it Narrow the key to the feed types that service reads.

3. Send the key in a header Authorization: Bearer <key>, Accept-Encoding: gzip. Never put the key in the URL.

4. Cache your polls Store the ETag and send If-None-Match next time, so an unchanged reply comes back as a cheap 304.

Related