Pular para o conteúdo principal

Autenticação

A API do Financeiro Inteligente usa Bearer Token para autenticar todas as requisições. Cada token é emitido para um Workspace e escopa automaticamente os dados retornados.

Obtendo o token​

Gere tokens via endpoint POST /api/v1/tokens ou pela interface administrativa. Cada token tem:

  • Identificador UUID público para rastreamento.
  • Secret mostrado uma única vez no momento da criação — copie e guarde em local seguro.
  • Escopos que limitam quais recursos o token pode acessar.
  • Expiração opcional.

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 Sistema (contato@minhaempresa.com.br)' \
  -X GET 'https://api.finance.kobana.com.br/v1/accounts'

Escopos​

Cada token deve declarar os escopos necessários. Escopos disponíveis:

EscopoAcesso
finance.accountsLeitura de contas
finance.accounts.writeCriação e atualização de contas
finance.payablesLeitura de contas a pagar
finance.payables.writeCriação e atualização de contas a pagar
finance.receivablesLeitura de contas a receber
finance.receivables.writeCriação e atualização de contas a receber
finance.transactionsLeitura de transações
finance.transactions.writeCriação e atualização de transações
finance.companiesLeitura de empresas
finance.companies.writeCriação e atualização de empresas
finance.peopleLeitura de pessoas
finance.people.writeCriação e atualização de pessoas
finance.categoriesLeitura de categorias
finance.categories.writeCriação e atualização de categorias
finance.cost_centersLeitura de centros de custo
finance.cost_centers.writeCriação e atualização de centros de custo
finance.taxesLeitura de impostos
finance.taxes.writeCriação e atualização de impostos
finance.attachmentsLeitura de anexos
finance.attachments.writeUpload e gerenciamento de anexos

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 — facilita rotacionar/revogar sem derrubar tudo.
  • Defina escopos mínimos necessários (princípio do menor privilégio).
  • Revogue imediatamente qualquer token vazado.
  • HTTPS obrigatório — chamadas em HTTP são rejeitadas.