Skip to main content
Every Developer API request authenticates with the X-API-Key header. Web-app bearer tokens do not work here, and vice versa.

​
A key identifies the tenant

Each key is bound to a single tenant — the X-Tenant-ID header is not needed for the Developer API and is ignored. The data a request returns is scoped to the key’s tenant.

​
Scopes

A key carries a set of scopes. An endpoint requires a specific scope, and the key must hold it, otherwise the request is rejected with DEVELOPER.SCOPE_INSUFFICIENT (HTTP 403). Scopes are the first gate. The second is the key owner’s permissions: even with employees:read, a key sees only the employees and fields available to the owner’s permission profile. Effective access is the intersection of the key’s scopes and the owner’s permissions.
Create a separate key per integration with the smallest set of scopes needed. If a key is compromised, you revoke just that one key, not your whole access.

​
Key lifecycle

  • Creation. Keys are created by a super-administrator in the app: Settings → Integrations → API. There is no key-creation endpoint in the Developer API itself — a key cannot mint other keys.
  • The secret is shown once, right at creation. Store it in a secret manager; it cannot be viewed again — lists show only the prefix (ddp_a1b2…).
  • Revocation. A key is revoked in the same settings page and stops working immediately.
  • Rotation. Create a new key with the same scopes, switch the integration over, then revoke the old one. Scheduled rotation every few months is good practice.
  • Owner permissions are live. A key’s access is computed on every request from the owner’s current permission profile: if the owner’s permissions narrow, so does the key’s access.

​
Redaction of sensitive fields

Fields the key owner is not allowed to see (for example the IIN) are dropped from the response, and their keys are listed in the redacted_fields array as object.field, e.g. persons.iin. A field missing from redacted_fields and an empty value are different things: the first means “hidden by permissions,” the second means “no data.”