Segurança

Sua chave de API de integração

A chave de API (X-API-Key) permite abrir uma sessão como qualquer um dos seus jogadores. Trate-a como a senha de um banco de dados.

Mantenha-a só nos seus servidores, em um cofre de segredos ou em variável de ambiente. Nunca em um navegador, um app móvel, uma URL ou um repositório.
A plataforma guarda só o hash SHA-256 dela e não consegue exibi-la de novo. Toda chamada com chave errada é recusada e auditada com o IP de origem.
Faça a rotação no back office em Configurações → Integração, ou com POST /api/v1/admin/integration/api-key (token de staff). A nova chave é devolvida uma única vez. Um tenant tem uma chave por vez, então a anterior para de funcionar quando a nova é emitida: deixe o deploy da nova chave pronto antes de rotacionar.

O segredo da sua carteira

O segredo da carteira assina toda chamada que fazemos à sua carteira (assinatura).

Mantenha-o nos servidores que rodam os seus endpoints de carteira; verifique toda requisição antes de interpretá-la, em tempo constante, com a janela de 300 segundos.
Faça a rotação em Configurações → Integração, ou com POST /api/v1/admin/integration/wallet-secret (token de staff). O novo segredo é devolvido uma única vez e a plataforma passa a assinar com ele a partir daí.

Origens permitidas

Só os seus sites podem enquadrar o sportsbook. Mantenha os embedOrigins restritos às origens exatas em que você o serve: a API transforma a lista em Content-Security-Policy: frame-ancestors, o que impede clickjacking e que outros sites incorporem o seu sportsbook, e o iframe só troca postMessage com essas origens (Incorporação). Tire as origens de homologação dos tenants de produção.

Allowlist de IP

As assinaturas já provam que uma chamada de carteira vem de nós. Como defesa em profundidade, aceite chamadas nos seus endpoints de carteira só dos endereços IP de saída da plataforma (o seu gerente de conta envia a lista por ambiente) e sirva-os só por HTTPS.

Tokens no navegador

A página só recebe launch tokens: de uso único, válidos por 120 segundos, guardados por nós só como hash, inúteis depois da troca.
O token de sessão vive na memória e no sessionStorage do iframe, sob a origem do sportsbook; assim os scripts da sua página não conseguem lê-lo, e ele some quando a aba fecha.
O iframe remove launch (e o antigo token) do próprio endereço assim que inicia, e a página que traz um deles é servida com Referrer-Policy: no-referrer; assim o token não aparece no histórico nem em cabeçalhos Referer.
O seu servidor guarda o token de sessão da resposta, ou o ignora. Não monte URLs com ele: ?token= ainda funciona para integrações existentes, que devem migrar para launch tokens.

Dados pessoais

Use um externalPlayerId opaco para vincular o sportsbook a um jogador já cadastrado e autenticado na sua plataforma. A validação de CPF, o KYC e os registros de identidade são responsabilidade da plataforma do cliente.

Campo	Necessário para
`externalPlayerId`	Ligar apostas e chamadas de carteira ao seu jogador. Use um id opaco, não um e-mail ou um CPF.
`displayName`	Nome de exibição opcional dentro do sportsbook; um apelido basta.

A solicitação de sessão não tem campos para documentos, selfies, e-mail, telefone, endereço ou data de nascimento. Mantenha esses registros de cadastro na sua plataforma. Não envie CPF: o campo legado cpf é ignorado. Nunca use CPF como externalPlayerId.

Apostas e ações da equipe ficam no log de auditoria, e callbacks da carteira no log de chamadas de carteira. O status de KYC delegado registra quem é responsável pelas verificações; não comprova que o OrbiSportbook as realizou.