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 na interface da plataforma, em Integrações → Token de API. 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. Um por recurso, em pares leitura/escrita:

Recurso	Leitura	Escrita
Contas financeiras	finance.accounts	finance.accounts.write
Catálogo de bancos	finance.banks	— (somente leitura)
Contas a pagar	finance.payables	finance.payables.write
Envio de conta a pagar ao banco	—	finance.payables.dispatch
Contas a receber	finance.receivables	finance.receivables.write
Transações	finance.transactions	finance.transactions.write (inclui transferências)
Conciliações	finance.reconciliations	finance.reconciliations.write (criação e dissolução)
Fluxo de caixa projetado	finance.cash_flow	— (somente leitura)
Empresas	finance.companies	finance.companies.write
Pessoas	finance.people	finance.people.write
Categorias	finance.categories	finance.categories.write
Centros de classificação	finance.cost_centers	finance.cost_centers.write
Regras automáticas	finance.automatic_rules	finance.automatic_rules.write (inclui reordenação)
Impostos	finance.taxes	finance.taxes.write
Anexos	finance.attachments	finance.attachments.write (upload e gerenciamento)
Coringa	finance.all (toda leitura)	finance.all.write (tudo)

Regras de resolução:

• Um escopo .write inclui a leitura do mesmo recurso — não é preciso conceder os dois.
• finance.all concede toda leitura, e nada de escrita. finance.all.write concede tudo.

aviso

Escopos de dinheiro são separados por segurança. finance.payables.dispatch (envio ao banco) nunca é concedido junto do .write por padrão, e o coringa de leitura finance.all não o satisfaz — só o grant exato ou finance.all.write. Assim um token de leitura não move dinheiro.

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.