Security

Your integration API key

The API key (X-API-Key) lets its holder open a session as any of your players. Treat it like a database password.

• Keep it on your servers only, in a secret manager or an environment variable. Never in a browser, a mobile app, a URL or a repository.
• The platform stores only its SHA-256 hash and cannot show it again. Every call with a wrong key is refused and audited with the caller’s IP.
• Rotate it in the back office under Configurações → Integração, or with POST /api/v1/admin/integration/api-key (staff token). The new key is returned once. A tenant has one key at a time, so the previous one stops working when the new one is issued: have the deployment of the new key ready before you rotate.

Your wallet secret

The wallet secret signs every call we make to your wallet (signature).

• Keep it on the servers that run your wallet endpoints; verify every request before parsing it, in constant time, with the 300-second window.
• Rotate it under Configurações → Integração, or with POST /api/v1/admin/integration/wallet-secret (staff token). The new secret is returned once and the platform signs with it from then on.

Rotate without refusing money

A 401 from your wallet is a final answer: a refused credit is not retried, it goes to manual review. So before rotating, make your wallet accept both secrets (try the new one, then the old one). Rotate, check that calls verify with the new secret, then remove the old one.

Allowed origins

Only your sites may frame the sportsbook. Keep embedOrigins to the exact origins you serve it from: the API turns the list into Content-Security-Policy: frame-ancestors, which stops clickjacking and other sites embedding your sportsbook, and the iframe only exchanges postMessage with those origins (Embedding). Remove staging origins from production tenants.

IP allowlisting

Signatures already prove that a wallet call comes from us. As defence in depth, accept calls to your wallet endpoints only from the platform’s outbound IP addresses (your account manager sends you the list per environment), and serve them over HTTPS only.

Tokens in the browser

• The page only ever receives launch tokens: single use, valid for 120 seconds, stored by us only as a hash, useless once exchanged.
• The session token lives in the iframe’s memory and sessionStorage, under the sportsbook’s origin, so your page’s scripts cannot read it and it is gone when the tab closes.
• The iframe removes launch (and the legacy token) from its address as soon as it starts, and the page that carries one is served with Referrer-Policy: no-referrer, so the token appears neither in the history nor in Referer headers.
• Your server keeps the session token from the response, or ignores it. Do not build URLs with it: ?token= still works for existing integrations, which should move to launch tokens.

Personal data

Use an opaque externalPlayerId to link the sportsbook to a player already registered and authenticated on your platform. Your platform owns CPF validation, KYC and the supporting identity records.

Field	Needed for
externalPlayerId	Linking bets and wallet calls to your player. Use an opaque id, not an email address or a CPF.
displayName	Optional display name inside the sportsbook; a nickname is enough.

The session request has no fields for identity documents, selfies, email, phone, address or birth date. Keep those onboarding records on your platform. Do not send CPF to the integration. The legacy cpf field is ignored; never use CPF as externalPlayerId.

Bets and staff actions are recorded in the audit log, and wallet callbacks in the wallet call log. The integration’s delegated KYC status records who is responsible for identity checks; it is not proof that OrbiSportbook verified them.