> ## Documentation Index
> Fetch the complete documentation index at: https://platform.doodocs.kz/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> API keys, scopes, and the permission model

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

```bash theme={null}
curl -H "X-API-Key: ddp_YOUR_KEY" \
  https://app.doodocs.kz/api/developer/v1/employees
```

## 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).

| Scope             | Access                                                     |
| ----------------- | ---------------------------------------------------------- |
| `employees:read`  | Read employees                                             |
| `documents:read`  | Read documents, types, categories, and templates; download |
| `documents:write` | Create documents, routes, sending, approval, signing       |
| `webhooks:manage` | Manage webhook subscriptions                               |
| `ingest:write`    | Bulk org-structure load (super-administrators only)        |

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.

<Tip>
  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.
</Tip>

## 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."