Autenticação e API keys

Todas as rotas da API pública do vario requerem uma API key válida. Este documento descreve como obtê-la, como usá-la em cada requisição e como gerenciá-la de forma segura ao longo do ciclo de vida da sua integração.

1. Autenticação

A API do vario utiliza API keys como mecanismo de autenticação. Cada key tem o prefixo vario_ e é incluída no header Authorization de cada requisição como um Bearer token.

Authorization: Bearer vario_SUA_API_KEY

Exemplo com curl:

curl https://api.vario.lat/v1/playbooks \
  -H "Authorization: Bearer vario_SUA_API_KEY"

Qualquer requisição sem esse header, ou com uma key inválida, inativa ou expirada, recebe uma resposta 401.

2. Como obter uma API key

Cadastro no portal

Cadastre-se no portal de desenvolvedores do vario informando seu e-mail corporativo e o nome da sua organização. Ao concluir o cadastro, o sistema gera automaticamente sua primeira API key e a exibe uma única vez na tela. Ela também é enviada para o e-mail cadastrado.

curl -X POST https://api.vario.lat/api/public/api-signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "org_name": "Escritório Forense LATAM"
  }'

Resposta 201:

{
  "key": "vario_xbGhABC123...WXYZ",
  "warning": "Store this key immediately. It cannot be recovered — only revoked and replaced.",
  "free_credits": 250,
  "call_cost_screening": 1,
  "call_cost_fast": 2,
  "call_cost_full": 3,
  "docs_note": "$0.150 per credit. Pricing is subject to change."
}

Ao se cadastrar, você recebe 250 créditos gratuitos para explorar a API.

Keys adicionais

Após o cadastro, você pode criar keys adicionais pelo portal ou via API. Isso é útil para separar credenciais por caso de uso, equipe ou projeto.

curl -X POST https://api.vario.lat/api/v1/api-keys \
  -H "Authorization: Bearer vario_SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Integração CADE matter 2026",
    "scopes": ["analyze:run", "playbooks:list"],
    "expires_at": "2027-06-01T00:00:00Z"
  }'

Resposta 201:

{
  "key_id": "uuid",
  "key": "vario_newXXX...ABC",
  "name": "Integração CADE matter 2026",
  "scopes": ["analyze:run", "playbooks:list"],
  "expires_at": "2027-06-01T00:00:00Z",
  "created_at": "2026-06-02T10:00:00Z",
  "warning": "Store this key immediately. It will not be shown again."
}

O campo key aparece apenas na resposta de criação. Depois disso, o portal exibe somente um key_hint (primeiros e últimos caracteres) para identificação visual — o token completo não pode ser recuperado.

3. Segurança da key

Uma API key do vario concede acesso aos endpoints do seu tenant. Trate-a como uma senha.

Boas práticas:

• Use variáveis de ambiente para injetar a key na sua aplicação. Nunca a escreva diretamente no código-fonte.
• Nunca inclua uma API key em código frontend (JavaScript do navegador, aplicações mobile). Keys são credenciais server-side.
• Nunca suba uma key para um repositório público (GitHub, GitLab, etc.). Se fizer isso por engano, revogue-a imediatamente e gere uma nova.
• Use keys separadas por contexto: uma para staging, outra para produção, outra por integração de terceiro quando aplicável.

# Correto: variável de ambiente
export VARIO_API_KEY="vario_SUA_API_KEY"

curl https://api.vario.lat/v1/analyze \
  -H "Authorization: Bearer $VARIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Escopos

Cada key tem um ou mais escopos que limitam os endpoints que ela pode invocar:

Se uma requisição usar uma key sem o escopo necessário, a API retorna 403 INSUFFICIENT_SCOPE. Ao criar uma key, conceda apenas os escopos necessários para aquele caso de uso.

4. Gestão de keys pelo portal

O portal de desenvolvedores exibe todas as API keys ativas do seu tenant. De lá você pode:

Listar keys ativas

curl https://api.vario.lat/api/v1/api-keys \
  -H "Authorization: Bearer vario_SUA_API_KEY"

Resposta 200:

[
  {
    "key_id": "uuid",
    "name": "Integração CADE matter 2026",
    "key_hint": "vario_xbGh...WXYZ",
    "scopes": ["analyze:run", "playbooks:list"],
    "is_active": true,
    "last_used_at": "2026-06-02T09:00:00Z",
    "expires_at": "2027-06-01T00:00:00Z",
    "created_at": "2026-06-02T10:00:00Z"
  }
]

O campo key_hint exibe os primeiros e últimos caracteres do token para que você possa identificar cada key visualmente sem expor o valor completo.

Revogar uma key

Quando uma key não está mais em uso, ou se você suspeitar que foi comprometida, revogue-a usando seu key_id. A revogação é imediata e irreversível.

curl -X DELETE https://api.vario.lat/api/v1/api-keys/{key_id} \
  -H "Authorization: Bearer vario_SUA_API_KEY"

Resposta: 204 No Content

A revogação desativa a key sem excluir seu registro. O histórico de uso é preservado no audit trail do tenant.

5. Rotação de keys

A rotação gera uma nova key com os mesmos escopos da atual e revoga a anterior em uma única operação atômica.

curl -X POST https://api.vario.lat/api/public/api-keys/rotate \
  -H "Authorization: Bearer vario_SUA_API_KEY"

Resposta 200:

{
  "key": "vario_newABC123...WXYZ",
  "key_hint": "vario_newABC...WXYZ",
  "warning": "Store immediately — not shown again."
}

Quando rotacionar:

• Suspeita de que a key foi exposta (repositório público, log visível, captura de tráfego).
• Rotação periódica como parte da política de segurança da sua organização.
• Mudança na equipe responsável pela integração.

O que acontece com as chamadas em andamento durante a rotação:

A key anterior fica inativa no momento em que o endpoint de rotação é executado. Qualquer requisição em trânsito que use a key anterior receberá 401 INVALID_API_KEY. Configure seu cliente para retentar com a nova key imediatamente após recebê-la.

6. Rate limits por key

Cada API key tem limites de taxa de acordo com o plano do tenant. Ao superar o limite, a API retorna 429 RATE_LIMIT_EXCEEDED com o header Retry-After indicando os segundos até o próximo slot disponível.

Os limites específicos por plano estão documentados em Erros e rate limits.

7. Exemplo completo de autenticação

# Cadastrar conta e obter a key inicial
curl -X POST https://api.vario.lat/api/public/api-signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "org_name": "Escritório Forense LATAM"
  }'

# Salvar a key da resposta como variável de ambiente
export VARIO_API_KEY="vario_xbGhABC123...WXYZ"

# Verificar acesso: listar playbooks disponíveis
curl https://api.vario.lat/v1/playbooks \
  -H "Authorization: Bearer $VARIO_API_KEY"

# Enviar um texto para análise
curl -X POST https://api.vario.lat/v1/analyze \
  -H "Authorization: Bearer $VARIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Combinamos não baixar de R$450 a unidade.",
    "playbook": "price_fixing",
    "language": "pt",
    "mode": "fast"
  }'

Erros de autenticação