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. This guide walks the OddsRelay access contract in plain terms, so integration holds no surprises.
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.
Keys: what they look 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.
- or_live_ (production) / or_test_ (sandbox) prefixes.
- Sent as Authorization: Bearer — never a query param.
- Shown once at mint; sha256-stored; revocable.
Scopes: four axes
A key is not all-or-nothing. It is scoped along four 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; price-boost as it builds).
- Regions — which regional views the key may request (UK today; more as coverage lands).
- Form — raw normalised prices or matched output.
- Add-ons — extras beyond the base feed, such as bet365 access on the raw feed.
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 not more requests — it is cheaper ones. Which brings us to caching.
Caching: 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. Poll on the matcher cycle, send If-None-Match, accept gzip.
At a glance
| Criterion | What to look for |
|---|---|
| Key handling | Bearer-only, shown once, revocableKeys in URLs leak into logs; unrevocable keys are a liability. |
| Scoping | Least-privilege scopes for what you useA narrowly-scoped key cannot be abused beyond what you licensed. |
| Caching | ETag/304 + gzipCheap polling is what makes a tight cadence affordable. |
| Cadence | Poll on the matcher cycle, not fasterFaster than the board changes wastes requests for nothing. |
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.
Key takeaways
- Keys are or_live_/or_test_, Bearer-only, shown once, sha256-stored, revocable.
- Scopes are four axes: feed types, regions, form, add-ons — least privilege by default.
- Rate limits are sized to the matcher cycle; polling faster buys nothing.
- ETag/304 + gzip make polling on the cycle cheap — that is the efficient pattern.
Where OddsRelay fits
This is how OddsRelay access works today: prefixed Bearer keys, four scope axes, cadence-sized rate limits, and ETag/304 + gzip caching, all documented in the API docs. A sandbox or trial key lets you integrate against the real contract before you commit — no surprises at cut-over.
Questions
Where do I put the API key?
In the Authorization header as a Bearer token — never in a query string or URL, where it would leak into logs and referrers. Keys are or_live_ (production) or or_test_ (sandbox).
What can a scope limit?
Four axes: which feed types the key may call, which regions it may request, the form of data (raw or matched), and add-ons such as bet365 on the raw feed. Least privilege keeps a key to exactly what you licensed.
How do I stay within rate limits?
Poll on the matcher cycle rather than as fast as possible — the board only changes on that cycle. Use ETag and If-None-Match for cheap 304s so most polls cost almost nothing.
What happens if a key leaks?
You rotate it: a new key is issued and the old one revoked. Because keys are sha256-stored and shown once, treat the raw secret like any production credential.
Keep reading
Done-for-you vs DIY
Skip the collection-and-matching stack, or own it — two products off the same backend.
Matched-betting data
Oddsmatcher-ready rows — back/lay paired, rated, gated, bet365 included.
Build vs buy
The real cost of building an odds pipeline yourself — and when buying wins.
Near-real-time vs delayed
What odds freshness actually means, how to measure it, and how much you really need.
Choosing a provider
The eight criteria that actually separate odds feeds — coverage, freshness, schema, support and more.
Developers
A predictable REST feed you integrate in an afternoon — no SDK, no collection to run, no matching engine.
For developers
What a developer-first odds API should give you — and how OddsRelay measures up.
API docs
Put the criteria to the test.
Start a free trial of the full UK feed, bet365 included, and judge it against everything in this guide.