Access

API Authentication

Two things let a request in: your API key, and the IP address of the server sending it. HZURA gives you the key and adds your server addresses to your allow-list. Both must be right, or the request is refused.

API key

HZURA gives you an API key. Send it with every Sports and Casino request. Only GET /api/v1/health works without it.

The key is shown to you once. Keep it on your server, like a password. Never put it in a website, a mobile app, or a code repository.

Header	Use	Note
`Authorization: Bearer <key>`	Recommended	If you send both headers, this one is used.
`X-Api-Key: <key>`	Alternative	Used when there is no `Authorization: Bearer` header.
`Accept: application/json`	Optional	Answers are JSON either way.

HTTP

GET /api/v1/sports HTTP/1.1
Host: api.hzura.com
Authorization: Bearer YOUR_API_KEY
Accept: application/json

An empty key counts as a wrong key.
Authorization is only read when it starts with Bearer.
A missing, empty, wrong or switched-off key, and a server address that is not on your allow-list, all get the same answer: 403 ip_not_allowed.

How HZURA knows who you are

Your API key tells HZURA which account is calling. You never send an account id. Every game, player and balance you see belongs to your account only.

The sports you can use and your sports rate limit also come from your account. GET /api/v1/sports lists exactly the sports you can use.

IP address allow-list

HZURA only accepts requests from the servers you registered. We check the public IP address your request comes from. Domain names do not count, only the IP address.

Addresses are written as single IPs or ranges in CIDR notation, for example 203.0.113.10 or 203.0.113.0/24. If your allow-list is empty, every request is refused.

Register the fixed public IP address of every server that will call the API. A laptop, a home connection or 127.0.0.1 is not a server address.

Sports accounts without a key

Some older Sports API accounts have no key. They are recognised by their server's IP address alone, and can use the Sports API only.

The Casino API always needs a key. A request without one gets 403 ip_not_allowed.

What each API needs

Route	API key	Server IP checked	Rate limit
`GET /api/v1/health`	Not needed	No	No
Sports routes	Needed, except on older key-less accounts	Yes	Yes
Casino providers, games, launch and wallet	Always needed	Yes	No

An address that does not exist answers not_found, but only after your access check passes. Otherwise it answers ip_not_allowed.

Good to know

Always call the API over HTTPS.
If your key may have leaked, ask HZURA for a new one.
Changes HZURA makes to your access, such as a new IP address, work within a few seconds.
A real sport that is not enabled for you is 403 sport_not_allowed. A sport that does not exist is 400 invalid_sport.
If casino is switched off for your account, casino requests get 403 casino_access_disabled. This is different from ip_not_allowed: your key and IP address are fine.
Launch and wallet requests refuse unknown JSON fields. Send only the documented fields.
Your sports rate limit is set for your account. When you hit it you get 429 with a Retry-After header: wait that many seconds.