Authentication

The Financeiro Inteligente API uses a Bearer Token to authenticate every request. Each token is issued for a Workspace and automatically scopes the data returned.

Getting the token

Generate tokens in the platform interface, under Integrations → API Token. Each token has:

• A public UUID Identifier for tracking.
• A Secret shown only once at creation time — copy it and keep it somewhere safe.
• Scopes that limit which resources the token can access.
• An optional Expiration.

How to send the token

Include the Authorization: Bearer <token> header on every request.

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'

Scopes

Each token must declare the scopes it needs. One per resource, in read/write pairs:

Resource	Read	Write
Financial accounts	finance.accounts	finance.accounts.write
Bank catalog	finance.banks	— (read-only)
Payables	finance.payables	finance.payables.write
Sending a payable to the bank	—	finance.payables.dispatch
Receivables	finance.receivables	finance.receivables.write
Transactions	finance.transactions	finance.transactions.write (includes transfers)
Reconciliations	finance.reconciliations	finance.reconciliations.write (create and dissolve)
Projected cash flow	finance.cash_flow	— (read-only)
Companies	finance.companies	finance.companies.write
People	finance.people	finance.people.write
Categories	finance.categories	finance.categories.write
Classification centers	finance.cost_centers	finance.cost_centers.write
Automatic rules	finance.automatic_rules	finance.automatic_rules.write (includes reordering)
Taxes	finance.taxes	finance.taxes.write
Attachments	finance.attachments	finance.attachments.write (upload and management)
Wildcard	finance.all (all reads)	finance.all.write (everything)

Resolution rules:

• A .write scope includes reading the same resource — there is no need to grant both.
• finance.all grants all reads, and no writes. finance.all.write grants everything.

warning

Money scopes are kept separate for security. finance.payables.dispatch (sending to the bank) is never granted alongside .write by default, and the read-only wildcard finance.all does not satisfy it — only the exact grant or finance.all.write does. That way a read-only token cannot move money.

Best practices

• Never commit tokens to git. Use environment variables or secret vaults (AWS Secrets Manager, Vault, etc.).
• Use distinct tokens per integration — this makes it easy to rotate/revoke without taking everything down.
• Set the minimum scopes required (principle of least privilege).
• Revoke any leaked token immediately.
• HTTPS is mandatory — calls over HTTP are rejected.