Autenticação e API Keys

Como gerar, usar e rotacionar a API key que autentica as chamadas à API externa da Arbitralis.

Toda chamada à API externa é autenticada pelo header X-API-KEY. A chave identifica o workspace e define o escopo de tudo que a integração pode ler e escrever.

Header de autenticação
X-API-KEY: arb_live_a1b2c3d4.9f8e7d6c5b4a39281706f5e4d3c2b1a09f8e7d6c5b4a39281706f5e4d3c2b1a0

Formato da chave

A chave tem duas partes separadas por ponto:

arb_live_a1b2c3d4 . 9f8e7d6c5b4a39281706f5e4d3c2b1a0…
└──── prefixo ────┘ └──────────── segredo ────────────┘
  • Prefixo (arb_live_ + 8 caracteres) — identifica a chave em logs e conversas com o suporte sem expor o segredo.
  • Segredo — 64 caracteres hexadecimais. A Arbitralis armazena apenas o hash SHA-256; o valor original não é recuperável.

Envie sempre a chave completa (prefixo + ponto + segredo) no header.

Gerar a primeira chave

A geração é feita por um administrador do workspace, autenticado no painel da Arbitralis — não pela própria API key.

Pré-requisitos
PapelADMIN ou MASTER_ADMINobrigatório

Apenas administradores do workspace podem gerar, consultar ou rotacionar API keys.

Chave por workspace1obrigatório

Cada workspace tem uma única chave ativa por vez. Para trocar, use o fluxo de rotação abaixo.

A resposta da geração devolve a chave em texto puro uma única vez:

201 Created
{
  "success": true,
  "data": {
    "apiKey": "arb_live_a1b2c3d4.9f8e7d6c5b4a39281706f5e4d3c2b1a09f8e7d6c5b4a39281706f5e4d3c2b1a0",
    "keyPrefix": "arb_live_a1b2c3d4",
    "createdAt": "2026-08-07T14:32:10.000Z"
  },
  "message": "API key generated successfully. Store it securely — it will not be shown again."
}

A chave não é exibida novamente

Copie e guarde o valor no seu cofre de segredos no momento da geração. Se ela for perdida, o único caminho é rotacionar — o que invalida a chave anterior.

Rotacionar a chave

A rotação exige confirmação por e-mail e acontece em duas etapas.

1. Solicitar o código

Um código de 6 dígitos é enviado ao e-mail do administrador autenticado. O código expira em 10 minutos e só pode ser usado uma vez.

200 OK
{
  "success": true,
  "data": {
    "message": "Confirmation code sent to your email."
  }
}

2. Confirmar a rotação

Com o código correto, a chave anterior é invalidada e uma nova é gerada e devolvida — também uma única vez.

Body
{
  "code": "483920"
}

Rotação é cutover imediato

Assim que a rotação é confirmada, a chave antiga para de funcionar. Planeje uma janela para atualizar o segredo em todos os seus ambientes antes de confirmar.

Respostas de autenticação

CódigoSituação
401 UNAUTHORIZEDHeader X-API-KEY ausente
401 UNAUTHORIZEDChave inválida, revogada, expirada ou inativa
429 TOO_MANY_AUTH_FAILURES20 tentativas inválidas do mesmo IP em 5 minutos
401 Unauthorized
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or inactive API key."
  }
}

Bloqueio por tentativas inválidas

Depois de 20 falhas de autenticação em 5 minutos, o IP é bloqueado temporariamente com 429. Se a sua integração entrar em loop de retry com uma chave errada, ela se auto-bloqueia — trate 401 como erro permanente e não faça retry automático.

Boas práticas de segurança

  • Nunca exponha a chave em frontend, aplicativo móvel, repositório ou log. Ela dá acesso total ao workspace.
  • Mantenha a chave em variável de ambiente ou cofre de segredos (Secret Manager, Vault, 1Password).
  • Chame a API sempre a partir do seu backend.
  • Rotacione a chave ao menos uma vez por ano e imediatamente em caso de suspeita de vazamento.
  • Ao abrir um chamado com o suporte, informe apenas o prefixo (arb_live_a1b2c3d4), nunca a chave completa.

Propagação da revogação

O contexto da chave é cacheado por até 60 segundos. Ao revogar ou rotacionar, o cache é invalidado imediatamente para a chave afetada, mas considere até 1 minuto de propagação em cenários de borda.