Skip to main content

API keys

API keys authenticate integrations with the API v1. They are created in Settings → Security, by administrators only.

API keys

Creating a key​

The form asks for:

  • Name (required) and description (optional) — identify the system that will use the key.
  • Access level (the key's scopes).
  • Expiration and emails to warn about expiry.

The full token is displayed only once, at creation, with a copy button. Store it in a secrets vault: after that, only the prefix (kb_ + last 8 characters) appears in the listing. Lost the token? Revoke the key and create another one.

Access levels​

LevelReach
FullAll resources, including account administration
Read and writeThe entire business operation (customers, charges, collection rules, agreements, disputes, tasks, webhooks...), without account administration: members, roles, API keys, settings, structure and audit are excluded
Read-onlylist/show on all resources, no writes

The levels are presets over the same dunning.dashboard.<recurso>.<ação> catalog as the team roles. Regardless of level, API-key calls to administrative resources respond 403 API_KEY_FORBIDDEN: a leaked key creates neither administrators nor other keys.

Expiration and warnings​

Optional expiration: never (default), 30, 90 or 365 days. For keys with a deadline:

  • The listing shows the date ("expires on 12/08/2026"), with an amber badge when 7 days or less remain and a red one when expired.
  • A daily job sends a warning email when the key enters the 7-day window, to the emails registered in the warning field (up to 10). Empty field: it warns whoever created the key.
  • The same warning arrives as an in-app notification (the bell), with urgent severity when 2 days or less remain.
  • The warning is sent only once per key (no daily spam).

Prefer keys with expiration: periodic rotation limits the damage of a leak.

Tracking usage​

The table shows, per key: name and description, access-level badge, prefix, origin, last use ("Never", if not yet used) and creation. "Last use: never" on an old key makes it a candidate for revocation.

Revoking​

The trash icon revokes the key (with confirmation). Revocation is immediate and permanent for the token: requests start responding 401. The key's record remains for history and audit purposes; later edits are limited to name and description.