Autenticação

A API do Financeiro Inteligente usa um access token da Conta Kobana para autenticar todas as requisições.

O token

O token é um JWT RS256 emitido pelo Authorization Server da Kobana (account.kobana.com.br). Esta API apenas o verifica, contra a chave pública que aquele servidor publica — ela não guarda chave de assinatura e não consegue emitir token nenhum.

Requisitos conferidos a cada requisição:

Claim	Exigência
iss	O identificador do Authorization Server, como URL: https://account[.{env}].kobana.com.br
aud	A URL desta API: https://api.finance[.{env}].kobana.com.br. Pode ser uma lista — a regra é contém, não igualdade
exp	Obrigatória. Token sem expiração é recusado
org	A conta Kobana em cujo nome o token age. É ela que resolve a organização aqui, e é obrigatória
sub	A pessoa (users.public_id). Vai para auditoria e atribuição; não escopa nada
jti	Id único do token — base da revogação e da auditoria

O workspace vem do header X-Workspace-Id: o org diz a organização, e uma organização pode ter vários workspaces. Ele é seletor, não concessão — um workspace de outra organização não é alcançável adivinhando o id. Sem o header, quando há mais de um workspace, a resposta é 400 WORKSPACE_REQUIRED.

:::caution Mudança em relação ao token gerado no dashboard Antes a credencial era um token gerado na plataforma, com secret exibido uma única vez. O mesmo valor assinava e verificava, então um vazamento em qualquer um dos dois lados era vazamento da emissão. Agora quem emite é o Authorization Server, e esta API só verifica. :::

Se o Authorization Server estiver inalcançável, a resposta é 5xx, nunca 401 — um 401 aí mandaria você depurar uma credencial boa durante uma indisponibilidade nossa.

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/financial-accounts'

Escopos

Os escopos têm dois eixos ortogonais: o recurso, sempre prefixado pelo app (finance/payables), e o verbo, um escopo global sem prefixo (write). Recurso sem verbo significa leitura. Escrever exige os dois: o escopo do recurso e o verbo.

Recurso	Escopo	O que a leitura cobre
Contas financeiras	finance/accounts	contas e saldos
Catálogo de bancos	finance/banks	só leitura, não há escrita
Contas a pagar	finance/payables	títulos a pagar
Contas a receber	finance/receivables	títulos a receber
Envio ao banco	finance/payable_dispatches	os envios de pagamento e seu estado
Emissão de cobrança	finance/receivable_charges	as cobranças (boleto/Pix) emitidas
Comprovantes de pagamento	finance/receipts	só leitura
Notas fiscais recebidas	finance/fiscal_documents	só leitura
Transações	finance/transactions	lançamentos e transferências
Conciliações	finance/reconciliations	conciliações (a escrita cobre criar e dissolver)
Fluxo de caixa projetado	finance/cash_flow	só leitura
Empresas	finance/companies
Pessoas	finance/people
Categorias	finance/categories
Centros de classificação	finance/cost_centers	o escopo nomeia o grant, por isso cost_centers e não classification-centers como na URL
Regras automáticas	finance/automatic_rules	a escrita inclui reordenar
Impostos	finance/taxes
Anexos	finance/attachments	a escrita cobre upload e gerenciamento
Coringa do recurso	finance/all	lê todos os recursos acima — e não concede verbo nenhum
Verbo global	write	toda escrita (POST, PUT, PATCH, DELETE) nos recursos que o token carrega

Dois exemplos: finance/payables lê títulos a pagar e não escreve; finance/payables write também cria, altera e apaga, e continua sem alcançar contas a receber.

A forma granular finance/payables:write é exceção da gramática, não o formato padrão: ela satisfaz os dois eixos para aquele recurso só, e existe para "lê um recurso, escreve outro". finance/* é curinga de cadastro e nunca é emitido num token — a comparação aqui é sempre literal. Na gramática por recurso, leitura é o recurso sem verbo; o read que existe é o nível de acesso da Conta Kobana, abaixo.

Regras de resolução:

• finance/all concede toda leitura, e escrita nenhuma. Para escrever é preciso o verbo: finance/all write.
• finance/receipts lista os comprovantes, mas não baixa o documento: o download_url aponta para o recurso de anexos, então buscar os bytes exige também finance/attachments.
• finance/fiscal_documents lista as notas recebidas, mas não baixa o XML: o xml_download_url aponta para o recurso de anexos, então buscar os bytes exige também finance/attachments.

aviso

Mover dinheiro é recurso próprio, não verbo próprio. Enviar um pagamento ao banco e emitir uma cobrança são sensíveis em grau diferente do resto da escrita, então cada um é um recurso: finance/payable_dispatches e finance/receivable_charges. Um token com finance/payables write grava título e não dispara pagamento; finance/all não alcança nenhum dos dois nem com o verbo write, porque o coringa cobre leitura e o dinheiro exige o recurso citado. Assim um token de operação comum não move dinheiro nem cobra ninguém.

Nível de acesso — o que é cobrado hoje

O escopo é cobrado em toda rota. Os escopos por recurso acima ainda não estão cadastrados na Conta Kobana, então os tokens que ela emite não os carregam — mas todo token traz o nível de acesso que você concedeu ao autorizar, e é ele que a API confere:

Nível	O que alcança
read	toda leitura (GET)
write	toda leitura e toda escrita, menos mover dinheiro
all	tudo, inclusive enviar pagamento ao banco e emitir cobrança

delete, import e export sozinhos não escrevem. Um cliente que se registra sozinho na Conta Kobana — um assistente de IA conectado pelo MCP, por exemplo — recebe só read.

Qualquer um dos vocabulários basta: o nível de acesso, os escopos por recurso acima ou os escopos finance.<recurso>[.write] dos tokens de desenvolvimento.

Quando o token traz escopos por recurso — o token pessoal que você cria na Conta Kobana, por exemplo —, são eles que definem o alcance, e read, write e all só valem dentro desses recursos: finance/payables read write lê e escreve contas a pagar e nada mais; finance/all read lê tudo e não escreve nada. Mover dinheiro exige o recurso próprio (finance/payable_dispatches, finance/receivable_charges) com write ou all. Faltando, a resposta é 403 INSUFFICIENT_SCOPE, com required, granted e accepted_levels — os níveis que teriam bastado — em details.

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.
• Peça os escopos mínimos necessários (princípio do menor privilégio) — read quando a integração só lê, e all só para quem precisa mover dinheiro.
• Revogue imediatamente qualquer token vazado.
• Aponte sempre para https:// — chamadas na porta 80 são redirecionadas para 443, mas clientes não reenviam o corpo num redirect.