Authentication

HMAC-SHA256 request signing, the canonical string, nonces, clock skew and test vectors.

On this page

Every API (application programming interface) request is signed with your secret using HMAC-SHA256. Your Partner identity (Provider or Operator) comes only from the key id in the signature, never from the request body.

Headers

HeaderExampleNotes
X-RX-KeyIdrxk_test_01Your key id.
X-RX-Timestamp2027-03-01T12:00:01ZUTC (Coordinated Universal Time), ISO 8601, second precision. Must be within ±60 s of our clock.
X-RX-Nonce9b2f0c1e-...Required on the endpoints marked nonce below; otherwise omit it. A fresh random value (e.g. a UUID) each time.
X-RX-SignatureJURcwkDh...Base64 of the HMAC-SHA256 of the canonical string.
Content-Typeapplication/jsonOn requests with a body.

Canonical string

Join these eight lines with a single line feed (\n, no trailing newline):

text
keyId
METHOD                 upper case, e.g. POST
host                   lower case, no port unless non-default, e.g. sandbox.reelxtra.net
path                   the full path exactly as sent, including the /v1/partner prefix, percent-encoded, e.g. /v1/partner/bets
sorted-query           query parameters sorted by name then value, percent-encoded (RFC 3986), joined with &; empty line if none
timestamp              the X-RX-Timestamp value
nonce                  the X-RX-Nonce value; empty line if the endpoint takes no nonce
body-hash              lower-case hex SHA-256 of the exact body bytes; SHA-256 of the empty string if no body

Rules:

  • The path is the full path as sent, with the /v1/partner prefix. The host is the one public host of the Site.
  • Duplicate query parameter names are rejected.
  • Hash the exact bytes you send. Don't re-serialise the JSON after signing.
  • signature = Base64( HMAC-SHA256( secret, canonicalString ) ).
  • Any mismatch is answered with HTTP 401 and error 1000, without saying which part was wrong.

Nonces

These endpoints change state without an idempotency key, so they require X-RX-Nonce: POST /v1/partner/sessions, POST /v1/partner/sessions/{sessionId}/launch (relaunch), DELETE /v1/partner/sessions/{sessionId}, POST /v1/partner/players/{playerId}/block, POST /v1/partner/players/{playerId}/unblock.

A nonce can be used once. POST /v1/partner/bets and the cancel call are made safe to repeat by your betId instead, so they take no nonce: retry them with exactly the same request.

A nonce endpoint can answer 503 9001 serviceUnavailable with Retry-After. After one of our servers has left the cluster (a failure or a deployment), the servers that took over its nonce records refuse, for at most 60 seconds, a request whose signed timestamp is not later than that moment plus 60 seconds, because they cannot tell whether its nonce was already used. This is not 1002: your nonce is not known to be reused. Wait for Retry-After, then send the request again with a new timestamp and a new nonce. Bets and cancels carry no nonce and are never affected.

Clock

Keep your servers on NTP (Network Time Protocol). If your timestamp is outside ±60 s you get error 1001 with our server time in the response body, so you can see the drift.

Test vectors

These use a published test secret that works nowhere. Use them to unit-test your signer.

ItemValue
Secretrx_test_secret_DO_NOT_USE_IN_PRODUCTION
Key idrxk_test_01
Timestamp2027-03-01T12:00:01Z

Vector 1: POST /v1/partner/bets

Body (exact bytes, no spaces). The vector only shows signing; a real bet body also carries level (see 05-bets.md):

json
{"sessionToken":"st_7f3a9c","betId":"b-000123","betCreatedAt":"2027-03-01T12:00:00.000Z","amount":"1.00","currency":"EUR"}

Canonical string (\n shown as line breaks):

text
rxk_test_01
POST
sandbox.reelxtra.net
/v1/partner/bets

2027-03-01T12:00:01Z

08f4e845ce17570a10ab4a814106f2aad99710432bb85d22e063d8f8ecbaa5fb

Signature: UJS/s/9nUxuvtYsmAMQG8X/9Raq7CY6T9Q7gOSzCYOY=

Vector 2: GET /v1/partner/games/reel-triple/levels?operatorId=op-42&currency=EUR

Sorted query: currency=EUR&operatorId=op-42. Body hash (empty body): e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855.

Signature: EVEX96zYx01cBPdgMlRtMwvX2UV8LRThdsd8L+1Ojs4=

Example signer (C#)

csharp
using System.Security.Cryptography;
using System.Text;

static string Sign(string secret, string keyId, string method, string host, string path,
                   IEnumerable<(string Name, string Value)> query,
                   string timestamp, string? nonce, byte[] body)
{
    var sortedQuery = string.Join("&", query
        .Select(p => (Name: Uri.EscapeDataString(p.Name), Value: Uri.EscapeDataString(p.Value)))
        .OrderBy(p => p.Name, StringComparer.Ordinal)
        .ThenBy(p => p.Value, StringComparer.Ordinal)
        .Select(p => $"{p.Name}={p.Value}"));

    var bodyHash = Convert.ToHexString(SHA256.HashData(body)).ToLowerInvariant();

    var canonical = string.Join("\n",
        keyId, method.ToUpperInvariant(), host.ToLowerInvariant(), path,
        sortedQuery, timestamp, nonce ?? "", bodyHash);

    var mac = HMACSHA256.HashData(Encoding.UTF8.GetBytes(secret), Encoding.UTF8.GetBytes(canonical));
    return Convert.ToBase64String(mac);
}

Send the same body bytes you hashed, and the same path and query values you signed.

Keeping keys safe

  • Store the secret in a secrets manager, never in code, config files or logs.
  • Call the API (application programming interface) only from your servers. Never put the secret or a sessionToken in a browser.
  • Rotate keys when staff with access leave, and at least yearly.