API da Autentify

Começo rápido

1. Crie sua conta no portal. Não há senha: você entra por um link enviado ao seu e-mail.
2. No menu API, gere a chave. Ela começa com aut_live_ e aparece uma única vez: guarde em um cofre de segredos ou em uma variável de ambiente.
3. Faça a primeira chamada:

curl -X POST https://gateway.autentify.com.br/v1/verify \
  -H "Authorization: Bearer $AUTENTIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"ana@empresa.com.br"}'

{
  "id": "vr_5f2c9a81d04e7b36a1c8e2f4",
  "email": "ana@empresa.com.br",
  "domain": "empresa.com.br",
  "verified_at": "2026-10-03T14:02:11.482913Z",
  "state": "deliverable",
  "reason": "accepted_email",
  "attributes": {
    "free": false,
    "role": false
  }
}

O endereço base é https://gateway.autentify.com.br. Não existe chave de teste: os créditos grátis da conta (20 para conta pessoal, 100 por mês para conta corporativa) servem para integrar e testar.

Autenticação

Envie a chave no cabeçalho Authorization: Bearer aut_live_... em toda requisição. A chave vale para todos os módulos e identifica a conta que paga pelas consultas.

• Guardamos só o hash da chave. Se você perder, gere outra.
• Gerar uma chave nova revoga a anterior na hora.
• Use a chave apenas no servidor. Nunca a coloque em páginas, aplicativos ou repositórios.

Módulos

Créditos e cobrança

Cada consulta respondida consome o número de créditos do módulo. A API reserva os créditos antes de consultar e só confirma a cobrança quando há resposta.

• Erros 5xx, tempo esgotado e dados recusados não são cobrados.
• No Verify, o resultado unknown (inconclusivo) também não é cobrado.
• Sem saldo, a resposta é 402 insufficient_credits e nada é consultado.

Para consultar o saldo:

GET/v1/account/balance

curl https://gateway.autentify.com.br/v1/account/balance \
  -H "Authorization: Bearer $AUTENTIFY_API_KEY"

{
  "total": 1250,
  "held": 40,
  "by_kind": {
    "free_monthly": 100,
    "paid": 1150
  }
}

Idempotência

Todo POST aceita o cabeçalho Idempotency-Key (até 128 caracteres, por exemplo um UUID). Use-o para repetir uma requisição com segurança depois de uma falha de rede, sem pagar duas vezes.

• Mesma chave e mesmo conteúdo, em até 24 horas: você recebe a resposta original, sem nova consulta nem nova cobrança.
• Mesma chave com outro conteúdo: 409 idempotency_conflict.
• A original ainda em andamento: 409 idempotency_in_progress.
• Requisições que falharam não ficam gravadas: pode tentar de novo com a mesma chave.

curl -X POST https://gateway.autentify.com.br/v1/verify \
  -H "Authorization: Bearer $AUTENTIFY_API_KEY" \
  -H "Idempotency-Key: 7d0a6a5c-2f1e-4b6a-9d55-0c1f6a1b2e33" \
  -H "Content-Type: application/json" \
  -d '{"email":"ana@empresa.com.br"}'

Limites

• Consultas unitárias: 20 por minuto, por conta e por módulo. Acima disso, 429 rate_limited com o cabeçalho Retry-After (segundos até o próximo minuto).
• Consultas simultâneas: até 3 por conta, somando todos os módulos. A quarta recebe 429 too_many_concurrent; espere uma das anteriores terminar.
• Chave errada: depois de 5 requisições com chave inválida ou ausente em 15 minutos, o IP recebe 429 too_many_failed_attempts até o fim desse período, mesmo com uma chave válida. O Retry-After diz quanto falta.
• Lotes: até 5.000 entradas por lote. Para volume no Verify e no Exposure, use lotes: eles têm fila própria e não contam nos limites acima.
• Precisa de limites maiores? Escreva para contato@autentify.com.br.

Erros

Todo erro tem o mesmo formato. Programe pelo code, que é estável; a message é um texto em português para leitura e pode mudar.

{
  "error": {
    "code": "insufficient_credits",
    "message": "Saldo insuficiente. Compre créditos para continuar."
  }
}

Erros 5xx e 429 são temporários: repita com espera crescente entre as tentativas. Erros 4xx pedem correção antes de repetir. Cada módulo pode ter códigos 422 próprios, descritos na página dele.

Suporte

Dúvidas de integração: contato@autentify.com.br. Sobre como tratamos os dados enviados, veja Segurança e LGPD.