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, settings) is never accessible through the API — it responds 403.

Keys can also be rotated: rotation creates a successor key with the same name, scopes and validity policy (token shown only once, as at creation) and brings the old key's expiration forward to the end of a grace window — 7 days by default, configurable from 0 to 30 (with 0, the old key is cut off immediately). Swap the secret in your integrations within that window; after it, the old key responds 401. The key lifecycle (rotation, status change, revocation) is published as api_key.* webhook events.

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
companies	list manage	account companies and branches (manage is blocked for keys — see below)
integrations	list manage	account integrations (manage is blocked for keys — see below)
audit	list show	audit trail (read-only)

Account administration

Members, roles, API keys and account settings make up account administration: a key, even with the Full preset, gets 403 (API_KEY_FORBIDDEN) when trying to reach them. Account and permissions are managed only through the dashboard. Companies/branches (companies) and integrations are readable with a key, but the configuration action (manage) is likewise blocked. The audit trail (GET /api/v1/audit-logs) is read-only and accessible through the API.

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.
• Rotate periodically: the rotation grace window lets you swap the secret with zero downtime; subscribe to the api_key.* events to follow along.
• Revoke any exposed key immediately — revocation is instantaneous (no grace window).
• HTTPS is mandatory on every call.