Authentication
Every casino endpoint authenticates with an API key that ByteFederal issues.
Send it in the X-API-Key header on every request.
curl https://quinix.byteconnect.us/casino/integration/key \
-H "X-API-Key: $API_KEY"
Key format
A key has the form <affiliate_id>:<secret>.
The part before the colon is your numeric affiliate id.
Send the whole string, exactly as issued.
Keys issued before this format are a single string with no colon. They authenticate the same way.
Ways to send the key
Use X-API-Key. The API also accepts the forms below.
| Where | Example | Notes |
|---|---|---|
X-API-Key header | X-API-Key: $API_KEY | Recommended. |
Api-Key header | Api-Key: $API_KEY | Same as X-API-Key. |
Authorization header | Authorization: ApiKey $API_KEY | Takes precedence over X-API-Key and Api-Key. |
JSON body field api_key | {"api_key": "...", ...} | Read only when no header carries a credential. Needs a JSON request body, so it does not suit GET endpoints. |
Authorization: Bearer <token> is for ByteConnect user sessions, not for casino integrations.
If a request carries a bearer token, the API uses it and ignores any API key on the same request.
GET /casino/integration/key describes API keys only and fails when called with a bearer token.
Send one credential per request.
What a key resolves to
Each key carries:
| Property | Values | Meaning |
|---|---|---|
| Affiliate | your affiliate | The account the key belongs to. Every request acts on this affiliate's entities only. |
| Entity scope | none, or one entity | None: the key can act on every entity under the affiliate. One entity: the key is locked to that casino. |
scope | admin, terminal | Casino endpoints require admin. |
mode | live, test | Whether deposits the key creates count toward US dollar settlement. |
expires_at | ISO 8601 UTC timestamp, or null | When the key stops working. null means it does not expire. |
GET /casino/integration/key shows all of these for the calling key.
See Quickstart.
Affiliate-wide and entity-scoped keys
An affiliate-wide key can act on any entity under your affiliate. BurraPay's platform normally uses one.
An entity-scoped key is locked to one casino. Requests that name a different entity are refused:
| Request | Result for another entity |
|---|---|
POST /casino/deposit_address with entity_id in the body | 403 "API key is scoped to a different entity" |
GET /casino/deposits?entity_id=... | 403 "API key is scoped to a different entity" |
POST /casino/integration/test-webhook with entity_id in the body | 403 "API key is scoped to a different entity" |
GET /casino/deposit/{id}, and accept, return, freeze on /casino/deposit/{id} | 404 "Deposit not found" |
Requests by deposit id return 404, not 403.
A scoped key cannot tell whether another casino's deposit exists.
For an entity-scoped key, GET /casino/integration/key returns that entity in entity_scope and lists only that entity in entities.
For an affiliate-wide key, entity_scope is null and entities lists every entity under the affiliate.
Key scope
A key's scope is admin or terminal.
Every casino endpoint, including /casino/integration/*, requires admin.
A terminal key gets:
{ "detail": "Insufficient permissions for this endpoint" }
with status 403.
Keys are admin unless ByteFederal issued them as terminal.
Live and test mode
A key's mode is live or test.
ByteFederal can also put a whole entity in test mode.
A new deposit is test data when either the key that creates it or its entity is in test mode. This is decided once, when the deposit is created.
Test mode changes one thing: test deposits are excluded from US dollar settlement. An accepted test deposit is never paid out to the casino by ACH.
Everything else is identical to live:
- The deposit gets a real mainnet address.
- The player sends real crypto, and ByteFederal receives it.
- Confirmations, KYT screening and OFAC screening run as normal.
- Webhooks for a test deposit look exactly like live ones. They carry no test marker.
- Accept, return and freeze behave the same. A return sends real crypto back.
Test mode moves real crypto on mainnet. Use small amounts. A deposit created with a live key on a live entity is real money and is settled once accepted.
key.mode in GET /casino/integration/key shows the key's mode.
The API does not report an entity's mode. Ask ByteFederal if you need to confirm it.
Only the test-webhook endpoint sends payloads with "test": true.
See Quickstart.
Authentication errors
Errors return a JSON body with a detail message.
See Errors for the full format.
| Status | detail | Cause |
|---|---|---|
| 401 | Token or API key missing | No credential in the request. |
| 401 | Invalid API key format | The key has a colon, but the part before it is not a number or the part after it is empty. |
| 401 | Invalid API key | No key matches. |
| 401 | API key has expired | The key's expires_at has passed. |
| 401 | API key is inactive | ByteFederal deactivated the key. |
| 401 | API key is revoked | ByteFederal revoked the key. |
| 403 | Affiliate account is disabled | Your affiliate account is disabled. Every key under it stops working. |
| 403 | Affiliate account is archived | Your affiliate account is archived. |
| 401 | API key has no affiliate, Affiliate not found, Affiliate has no user, User not found | The account behind the key is misconfigured. Contact ByteFederal. |
| 403 | Insufficient permissions for this endpoint | The key's scope is terminal. |
| 403 | API key is scoped to a different entity | An entity-scoped key named another entity. |
Expiry, status and the affiliate account are checked on every request. A revoked or expired key fails on its next request.
Ask ByteFederal for a replacement key before expires_at.
A webhook URL can be set on an API key (source: "api_key" in GET /casino/integration/key).
That URL is used only while its key is active and unexpired.
When that key expires or is revoked, webhooks stop going to its URL.
They go to the URL on another active key that covers that casino (a key scoped to that casino, or an affiliate-wide key), if one has a URL, or nowhere.
Check the webhook of each entity after any key change.
Keep keys secret
An API key can create deposits and accept, return or freeze them. Treat it like a password.
- Call the API only from your servers.
- Never put a key in a browser, a mobile app, or any code that runs on a player's device.
- Never put a key in a URL, a log line or a support ticket.
- Store keys in a secrets manager or environment variable, not in source control.
If a key leaks, ask ByteFederal to revoke it.