Skip to main content

Autenticação

A API do Faturamento Automático usa Bearer Token para autenticar todas as requisições. Cada token é emitido para uma Organização e escopa automaticamente os dados retornados.

Obtendo o token​

Gere e gerencie tokens no dashboard em Configurações → API → API Keys. Cada token tem:

  • Prefix público (visível para identificar a chave).
  • Secret mostrado uma única vez no momento da criação — copie e guarde em local seguro.
  • Status (active ou revoked).
  • Expiração opcional.

Tokens podem ser rotacionados sem invalidar o anterior imediatamente, permitindo migração gradual.

Confira o ambiente

O token é diferente entre Sandbox e Produção. Não reutilize entre ambientes.

Como enviar o token​

Inclua o cabeçalho Authorization: Bearer <token> em cada requisição.

export KOBANA_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxx

curl -i \
  -H "Authorization: Bearer $KOBANA_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'User-Agent: Meu Nome (meunome@example.com)' \
  -X GET 'https://api.billing.sandbox.kobana.com.br/v1/me'

Requisição válida​

Com um token válido, a resposta traz dados da Organização autenticada.

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Request-Id: req_01HABCDEF

{
  "id": "org_01HORG",
  "name": "Minha Empresa",
  "email": "contato@minhaempresa.com.br",
  "document_type": "cnpj",
  "document_number": "12345678000190",
  "environment": "sandbox",
  "created_at": "2026-01-01T00:00:00.000Z"
}

Requisição inválida​

Token ausente, malformado ou revogado retorna 401 Unauthorized.

curl -i \
  -H "Authorization: Bearer tokeninvalido" \
  -H 'Content-Type: application/json' \
  -H 'User-Agent: Meu Nome (meunome@example.com)' \
  -X GET 'https://api.billing.sandbox.kobana.com.br/v1/me'
HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8

{
  "error": "Token de acesso inválido ou expirado.",
  "error_code": "unauthorized"
}

Boas práticas​

  • Nunca versione tokens em git. Use variáveis de ambiente ou cofres (AWS Secrets Manager, Vault, etc.).
  • Use tokens distintos por integração (CRM, ERP, frontend, etc.) — facilita rotacionar/revogar sem derrubar tudo.
  • Defina expiração quando possível. Tokens com expiração próxima geram alertas no dashboard.
  • Revogue imediatamente qualquer token vazado.
  • HTTPS obrigatório — chamadas em HTTP são rejeitadas.