Authentication

The Smart Finance 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: My System (contact@mycompany.com)' \
  -X GET 'https://api.finance.kobana.com.br/v1/financial-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
Issuing and cancelling a charge (bank slip/Pix)	—	finance.receivables.charge
Payment receipts	finance.receipts	— (read-only)
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.
• finance.receipts lists receipts but does not download the document: download_url points at the attachments resource, so fetching the bytes also requires finance.attachments.

warning

Money scopes are kept separate for security. finance.payables.dispatch (sending to the bank) and finance.receivables.charge (issuing a charge) are never granted alongside .write by default, and the read-only wildcard finance.all does not satisfy them — only the exact grant or finance.all.write does. That way a read-only token can neither move money nor bill anybody.

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.
• Always point at https:// — calls on port 80 are redirected to 443, but clients do not resend the body on a redirect.