Buyer guide
API keys, scopes and rate limits
Before you integrate an odds feed, it helps to understand how access actually works: what a key looks like, how scopes limit it, how rate limits and caching behave. The OddsRelay access contract, in plain terms.
6 min read
Access to an odds feed is more than a URL and a token. How keys are shaped, what a scope limits, how rate limits and caching behave: these decide how cleanly the feed fits your stack.
This guide covers the OddsRelay access contract at a level useful for planning an integration. It is the shape of things, not a secret: the full reference lives in the API docs.
What a key looks like
OddsRelay keys are prefixed so you always know what you are holding: or_live_ for production and or_test_ for sandbox. You send the key as a Bearer token in the Authorization header, never in a query string, never in a URL.
Keys are stored hashed (sha256), so the raw secret is shown exactly once, at mint. If a key leaks, you rotate it and the old one is revoked. Treat a key like any other production secret.
The scope axes
A key is not all-or-nothing. It is scoped along three axes, so it can carry exactly the access you licensed and no more.
This matters for security and for cost: a key scoped to what you use cannot be abused to pull what you did not license, and it keeps your integration honest about what it depends on.
- Feed types: which matcher types the key may call (standard, each-way, extra-place, BOG, dutching, 2Up).
- Regions: which regional views the key may request (UK today; more as coverage lands).
- Form: raw normalised prices or matched output.
Rate limits sized to the cadence
The feed refreshes on a matcher cycle, so there is no value in hammering it faster than it changes. Rate limits are sized to sensible polling on that cadence.
The efficient pattern is to make each request cheaper. Which brings us to caching.
Cheap polling with ETag and 304
Every response carries an ETag. Send it back as If-None-Match on your next request and, if the board has not changed, you get a cheap 304 Not Modified instead of the full payload.
Combined with gzip, this means you can poll on the cycle without re-downloading an unchanged board: the difference between polling that scales and polling that gets expensive.
Step by step
- 01
Get a key
Start with an or_test_ sandbox key or a trial or_live_ key. Store it as a secret. It is shown once.
- 02
Scope it
Limit the key to the feed types, regions, form and add-ons you actually use.
- 03
Send it right
Authorization: Bearer <key>, Accept-Encoding: gzip. Never put the key in the URL.
- 04
Cache your polls
Store the ETag, send If-None-Match next time, and poll on the matcher cycle for cheap 304s.
Where OddsRelay fits
A sandbox or trial key lets you integrate against this exact contract before you commit, with no surprises at cut-over.
Put the criteria to the test.
Start a free trial of the full UK feed and judge it against everything in this guide.