Axiom API

Status da implementação

• GET /api/healthNo ar
• GET /openapi.jsonNo ar
• GET /api/v1/organizationNo ar
• GET /api/v1/organization/entitlementsNo ar
• GET /api/v1/gamesNo ar
• POST /api/v1/playersNo ar
• GET /api/v1/playersNo ar
• GET /api/v1/players/{playerId}No ar
• GET /api/v1/walletNo ar
• POST /api/v1/walletsNo ar
• GET /api/v1/wallets/{walletId}No ar
• POST /api/v1/wallets/{walletId}/creditNo ar
• POST /api/v1/sessionsNo ar
• GET /api/v1/sessions/{sessionId}No ar
• POST /api/v1/webhooksNo ar
• GET /api/v1/webhooksNo ar
• POST /api/v1/webhooks/deliveries/{deliveryId}/retryNo ar
• GET /api/v1/auditNo ar
• GET /api/v1/audit/{eventId}No ar

Primeiros 5 minutos

O cadastro cria uma organização com uma Subscription ativa no plano técnico Sandbox. Crie uma API key sandbox no dashboard. GET /api/v1/games lista Dice. Players, a carteira virtual, as sessões de Dice e os webhooks estão no ar.

1. Criar conta
2. Organização criada automaticamente
3. Criar uma API key sandbox (exibida uma vez)
4. Ler esta documentação
5. GET /api/v1/games (no ar)
6. POST /api/v1/players (no ar)
7. GET /api/v1/players (no ar)
8. POST /api/v1/wallets (no ar)
9. POST /api/v1/sessions (Dice) (no ar)
10. Receber o resultado na mesma resposta (no ar)
11. POST /api/v1/webhooks (no ar)
12. GET /api/v1/audit (no ar)
13. GET /api/v1/organization (no ar)
14. GET /api/v1/organization/entitlements (no ar)
15. GET /api/v1/wallet (no ar)

Ambiente

Axiom define hoje um único ambiente: sandbox. Não há ambiente live. As chaves usam o prefixo aur_sk_sandbox_. Todos os saldos são créditos virtuais.

Autenticação

Rotas de negócio exigem Authorization: Bearer aur_sk_sandbox_.... O secret é exibido uma vez na criação e armazenado como hash HMAC-SHA256. Chaves ausentes, malformadas, inválidas e revogadas retornam o mesmo 401. A organização é derivada da chave e nunca enviada pelo cliente como campo confiável.

Organizações

A organização é o tenant. O cadastro cria uma organização, um membership com papel owner e uma Subscription ativa no plano técnico Sandbox. GET /api/v1/organization e GET /api/v1/organization/entitlements devolvem só o tenant da API key. Não há CRUD público de organizações, planos ou subscriptions. organizationId nunca é enviado pelo cliente.

curl https://YOUR_HOST/api/v1/organization \
  -H "Authorization: Bearer aur_sk_sandbox_YOUR_KEY"

curl https://YOUR_HOST/api/v1/organization/entitlements \
  -H "Authorization: Bearer aur_sk_sandbox_YOUR_KEY"

API Keys

Chaves sandbox são criadas no dashboard. Só o prefixo fica visível depois. A revogação é imediata. GET /api/v1/games, as rotas de player, wallet, sessions e webhooks ficam disponíveis depois de uma chave válida.

Games

GET /api/v1/games está no ar. Lista os jogos publicados no sandbox. O primeiro jogo é Dice. A execução pública de sessão está em POST /api/v1/sessions. Outros tipos de jogo não fazem parte deste contrato.

curl https://YOUR_HOST/api/v1/games \
  -H "Authorization: Bearer aur_sk_sandbox_YOUR_KEY"

Players

POST /api/v1/players cria um player na organização derivada da API key. externalRef é obrigatório e único por organização, não globalmente. GET lista os players dessa organização. GET /api/v1/players/{playerId} busca por id e organização juntos. Acesso cross-tenant retorna 404. Criar um player não cria uma carteira.

curl -X POST https://YOUR_HOST/api/v1/players \
  -H "Authorization: Bearer aur_sk_sandbox_YOUR_KEY" \
  -H "Idempotency-Key: 01demo-create-player" \
  -H "Content-Type: application/json" \
  -d '{"externalRef":"customer-123","displayName":"Sandbox Player"}'

curl https://YOUR_HOST/api/v1/players \
  -H "Authorization: Bearer aur_sk_sandbox_YOUR_KEY"

curl https://YOUR_HOST/api/v1/players/PLAYER_ID \
  -H "Authorization: Bearer aur_sk_sandbox_YOUR_KEY"

Wallet

POST /api/v1/wallets cria um ledger vazio de créditos virtuais para um player na organização chamadora. Uma wallet por player. O saldo é derivado de lançamentos append-only de credit, debit e refund. Créditos são inteiros, não dinheiro. Criar um player não cria uma carteira.

curl -X POST https://YOUR_HOST/api/v1/wallets \
  -H "Authorization: Bearer aur_sk_sandbox_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"playerId":"PLAYER_ID"}'

curl https://YOUR_HOST/api/v1/wallets/WALLET_ID \
  -H "Authorization: Bearer aur_sk_sandbox_YOUR_KEY"

curl "https://YOUR_HOST/api/v1/wallet?playerId=PLAYER_ID" \
  -H "Authorization: Bearer aur_sk_sandbox_YOUR_KEY"

curl -X POST https://YOUR_HOST/api/v1/wallets/WALLET_ID/credit \
  -H "Authorization: Bearer aur_sk_sandbox_YOUR_KEY" \
  -H "Idempotency-Key: 01demo-wallet-credit" \
  -H "Content-Type: application/json" \
  -d '{"amount":100}'

curl -X POST https://YOUR_HOST/api/v1/wallets/WALLET_ID/debit \
  -H "Authorization: Bearer aur_sk_sandbox_YOUR_KEY" \
  -H "Idempotency-Key: 01demo-wallet-debit" \
  -H "Content-Type: application/json" \
  -d '{"amount":30}'

curl -X POST https://YOUR_HOST/api/v1/wallets/WALLET_ID/refund \
  -H "Authorization: Bearer aur_sk_sandbox_YOUR_KEY" \
  -H "Idempotency-Key: 01demo-wallet-refund" \
  -H "Content-Type: application/json" \
  -d '{"amount":30,"reference":"TRANSACTION_ID"}'

Game Sessions

POST /api/v1/sessions inicia uma sessão síncrona de Dice para um player na organização chamadora. O stake é debitado da carteira virtual, o engine executa, e o payout é creditado quando o resultado exige. Uma loss deixa o stake debitado. Criar um player não cria uma carteira; a carteira precisa existir antes.

curl -X POST https://YOUR_HOST/api/v1/sessions \
  -H "Authorization: Bearer aur_sk_sandbox_YOUR_KEY" \
  -H "Idempotency-Key: 01demo-dice-session" \
  -H "Content-Type: application/json" \
  -d '{"playerId":"PLAYER_ID","game":"dice","gameVersion":"1.0.0","stake":10,"config":{"target":4}}'

curl https://YOUR_HOST/api/v1/sessions/SESSION_ID \
  -H "Authorization: Bearer aur_sk_sandbox_YOUR_KEY"

curl https://YOUR_HOST/api/v1/sessions \
  -H "Authorization: Bearer aur_sk_sandbox_YOUR_KEY"

Webhooks

POST /api/v1/webhooks registra uma URL HTTPS para session.completed e session.cancelled. O secret de assinatura HMAC-SHA256 é exibido uma vez. A garantia é: primeira entrega best-effort + registro durável + retry explícito. Não há worker nem retry automático. O webhook nunca desfaz débito, payout ou reabre uma sessão terminal.

curl -X POST https://YOUR_HOST/api/v1/webhooks \
  -H "Authorization: Bearer aur_sk_sandbox_YOUR_KEY" \
  -H "Idempotency-Key: 01demo-create-webhook" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://hooks.example.com/aurora","events":["session.completed","session.cancelled"]}'

curl https://YOUR_HOST/api/v1/webhooks \
  -H "Authorization: Bearer aur_sk_sandbox_YOUR_KEY"

curl https://YOUR_HOST/api/v1/webhooks/WEBHOOK_ID \
  -H "Authorization: Bearer aur_sk_sandbox_YOUR_KEY"

curl https://YOUR_HOST/api/v1/webhooks/WEBHOOK_ID/deliveries \
  -H "Authorization: Bearer aur_sk_sandbox_YOUR_KEY"

curl -X POST https://YOUR_HOST/api/v1/webhooks/deliveries/DELIVERY_ID/retry \
  -H "Authorization: Bearer aur_sk_sandbox_YOUR_KEY"

Audit Trail

GET /api/v1/audit lista fatos de negócio já persistidos, sanitizados e paginados por cursor. GET /api/v1/audit/{eventId} busca um fato. A organização vem da API key e não aparece na resposta. Audit não é ledger, sessão nem delivery. Não inclui secrets, seeds nem lastError de webhook. Não há POST, PUT, PATCH ou DELETE.

curl "https://YOUR_HOST/api/v1/audit?sessionId=SESSION_ID&limit=20" \
  -H "Authorization: Bearer aur_sk_sandbox_YOUR_KEY"

curl https://YOUR_HOST/api/v1/audit/EVENT_ID \
  -H "Authorization: Bearer aur_sk_sandbox_YOUR_KEY"

Créditos virtuais

Código da moeda: CREDITS. Os valores são inteiros. Créditos não podem ser depositados, sacados nem convertidos em dinheiro. Existem para o integrador testar o runtime.

Idempotência

Credit, debit e refund da wallet, POST /sessions e POST /webhooks exigem Idempotency-Key (16-64 caracteres) e devolvem o resultado original para a mesma organização e payload. Reutilizar a chave em outra operação retorna 409. POST /players valida o header sem replay.

Erros

Todos os erros usam o mesmo envelope. Rotas de player, wallet, session e webhook retornam erros 4xx reais, incluindo 422 para saldo insuficiente. ENTITLEMENT_LIMIT_EXCEEDED (422) só aparece quando um entitlement de estoque definido foi excedido. USAGE_LIMIT_EXCEEDED (422) aparece quando a cota diária de execuções de sessão é excedida.

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Insufficient virtual credits.",
    "requestId": "3b0c1f2e-7d64-4a11-9c0a-12ab34cd56ef"
  }
}

OpenAPI

Baixe ou consulte o contrato em formato máquina em /openapi.json. Trate-o como a fonte da verdade. SDKs serão gerados a partir dele depois. Ainda não estão disponíveis.