Integration

Authentication and security

API key#

Every server-to-server call carries two body fields:

Requests to the platform carry no tokens in headers: the key travels in the JSON body over HTTPS. Keep it only on your server: never in a browser, mobile app or log. A request with an unknown partner or a wrong api_key is answered with HTTP 401 UNAUTHORIZED; the two cases are indistinguishable on purpose.

Public read-only endpoints need no key: GET /games/health, GET /games/catalog, GET /capabilities, GET /health, GET /docs/openapi.json (Catalog).

IP allowlist#

POST /gameActions.do (free spins, target outcomes, round_cancel, report_*) and POST /playerRtp.do additionally require the caller's IP address to be inside one of the networks allowed for the project. The key is checked first, then the address: a wrong key gives UNAUTHORIZED, a correct key from an unlisted address gives HTTP 403 IP_NOT_ALLOWED.

• Networks are written as CIDR, IPv4 or IPv6 (203.0.113.0/24, 203.0.113.7/32, 2001:db8::/32).
• The allowlist is managed in the admin panel, section IP Whitelist, by the platform owner or by your own staff with the manage credentials permission (see Admin panel).
• Make every server call from the same fixed addresses and ask for exactly those to be allowed. IPv4-mapped IPv6 addresses are treated as their IPv4 form.

Rotating and revoking the API key#

In the admin panel (Projects → project → Integration) the platform owner, and your own staff with the manage credentials permission, can rotate and revoke the key:

• Regenerate (rotate) asks you to type the project id as confirmation, creates a new key, and the old key stops working immediately. Install the new key on your server before regenerating if you cannot tolerate failed calls, or be ready to deploy it at once. The callback signing secret derived from the key changes with it (Callback signature).
• Revoke disables the key without issuing a new one: no key matches and every call answers UNAUTHORIZED until a key is generated again.
• Reveal shows the current key, is recorded in the audit log and is available to the owner only.
• The panel shows a fingerprint of the key so you can check which key a server uses without exposing it.

Projects that are internal to the platform (demo and site wallet) have a read-only key.

Verifying the platform's callbacks#

The platform calls your wallet with the same api_key in the JSON body of every callback. Compare it with your stored key (in constant time) and reject the request on a mismatch. In addition, every callback is signed with HMAC-SHA256 (X-Notell-Timestamp, X-Notell-Signature; canonical string, secret and test vector in Callback signature) and leaves the platform from fixed addresses published in callbackSourceIps of GET /capabilities; allowlist them. Also:

• accept callbacks only on an https:// address you control;
• the platform does not follow redirects and waits at most 2 seconds for an answer;
• the callback URL must be public: https://, port 443, no user info, query or fragment, no trailing slash, at most 512 characters, and a host that resolves to public addresses only.

Connection handling, retries and the answer format: Wallet callbacks.

Quotas and replays#

Per-project request quotas and the Idempotency-Key header are described once, in Conventions. Every wallet operation carries a unique meta.transaction, which protects the wallet against duplicates after a timeout.

Security checklist#

• [ ] The key is stored in a secret manager or environment variable.
• [ ] Calls are made from allowlisted servers only.
• [ ] The wallet endpoint verifies api_key and X-Notell-Signature, uses HTTPS, is idempotent and accepts only the platform's callback IPs.
• [ ] Logs never contain the key or the game link.
• [ ] Staff accounts in the admin panel have the minimum permissions and projects they need.