Authentication

Every request carries an API key. The API accepts two equivalent headers — use whichever you prefer:

Authorization: Bearer <your-key>

x-api-key: <your-key>

The key is never stored in plaintext on our side (only its SHA-256 hash) and identifies your organization: all returned data is automatically scoped to it.

Creating keys

Create keys in the dashboard under Settings → Security, with three access levels:

• Full — the entire API.
• Read and write — the entire collection operation, without account administration.
• Read only — GET only.

Scopes follow the dunning.dashboard.<resource>.<action> catalog; a key with no scopes has full business access. The key is shown only once at creation — copy it and store it somewhere safe.

Keys can have an expiration (30/90/365 days) with an email warning before they expire. Account administration (members, roles, keys, organizational structure) is never accessible through the API — it responds 403.

Scopes

Each scope is dunning.dashboard.<resource>.<action>. Wildcards are accepted: dunning.dashboard.charges.* (all charge actions) or dunning.dashboard.* (everything).

Presets

When creating a key you pick a preset; all three derive from the same catalog:

Preset	Covers	Typical use
Read only	list/show/view actions on all resources	mirroring data, BI, dashboards — never changes anything
Read and write	the entire collection operation (all resources, except account administration)	ERP/CRM integrations that create and update customers, charges, agreements...
Full	dunning.dashboard.*	everything a key can reach

A key created with no scopes is equivalent to "Read and write" (full business access). You can also assemble a tailored set by picking individual scopes from the catalog below.

Resource catalog

Resource	Actions	What it grants
dashboard	view	read the panel's metrics
people	list show create update delete	customer/debtor portfolio
charges	list show create update delete notify	charges and manual notification triggering
collection_rules	list show create update delete activate	collection rules and their activation
classifications	list show create update delete	portfolio classifications/tags
templates	list show create update delete duplicate	message templates
notifications	list show create update resend delete	notifications and resending
tasks	list show create update delete complete	operation tasks
interactions	list show create update delete	interactions/contact history
agreements	list show create update cancel	payment agreements
disputes	list show create resolve	disputes and their resolution
negativations	list show create approve cancel	credit bureau registration
protests	list show create approve cancel	notarial protest
portal	generate_link revoke_link	debtor portal links
webhooks	list show create update delete	webhook endpoints
email_layouts	list show create update delete	email layouts
imports	list show create	batch imports
exports	create	data exports
integrations	list manage	account integrations

Account administration

Members, roles, API keys, workspaces, audit and account settings make up account administration. These resources exist in the catalog for the dashboard roles, but no account-administration route is exposed in the API: a key, even with the Full preset, gets 403 when trying to reach them. Account and permissions are managed only through the dashboard.

Valid request

export DUNNING_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxx

curl -i \
  -H "Authorization: Bearer $DUNNING_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'User-Agent: My Integration <dev@mycompany.com>' \
  -X GET 'https://api.dunning.kobana.com.br/api/v1/charges?per_page=1'

HTTP/1.1 200 OK
Content-Type: application/json
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 599

{
  "data": [
    {
      "id": "cmd8k2p4x0001ab3f",
      "status": "overdue",
      "amount": "1500.00",
      "dueDate": "2026-07-10T00:00:00.000Z",
      ...
    }
  ],
  "meta": { "total": 142, "page": 1, "limit": 1, "totalPages": 142 }
}

Invalid request

A missing, malformed, revoked, or expired key responds 401 with the standard error envelope:

curl -i \
  -H "Authorization: Bearer invalid-key" \
  -X GET 'https://api.dunning.kobana.com.br/api/v1/charges'

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "message": "Não autorizado",
  "code": "UNAUTHORIZED"
}

A valid key without the required scope responds 403 with code: "FORBIDDEN" (or API_KEY_FORBIDDEN) and a required field indicating the missing permission.

Best practices

• Never commit keys to git. Use environment variables or secret vaults (Vault, AWS Secrets Manager...).
• Use one key per integration (ERP, CRM, BI...) — revoking one doesn't break the others, and the audit trail stays readable.
• Prefer the lowest access level that does the job: read-only integrations don't need write access.
• Set an expiration whenever possible; the email warning arrives before it lapses.
• Revoke any exposed key immediately — revocation is instantaneous.
• HTTPS is mandatory on every call.