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

# Аутентификация

> Ключи API, области доступа и модель прав

Все запросы Developer API аутентифицируются заголовком `X-API-Key`. Bearer-токены
веб-приложения здесь не работают и наоборот.

```bash theme={null}
curl -H "X-API-Key: ddp_ВАШ_КЛЮЧ" \
  https://app.doodocs.kz/api/developer/v1/employees
```

## Ключ определяет тенант

Каждый ключ привязан к одному тенанту — заголовок `X-Tenant-ID` для Developer API
не нужен и игнорируется. Данные, которые вернёт запрос, ограничены тенантом ключа.

## Области доступа (scopes)

Ключ несёт набор областей. Ручка требует конкретную область, и ключ должен ею
обладать, иначе запрос отклоняется с `DEVELOPER.SCOPE_INSUFFICIENT` (HTTP 403).

| Область           | Доступ                                                            |
| ----------------- | ----------------------------------------------------------------- |
| `employees:read`  | Чтение сотрудников                                                |
| `documents:read`  | Чтение документов, типов, категорий и шаблонов; скачивание        |
| `documents:write` | Создание документов, маршруты, отправка, согласование, подпись    |
| `webhooks:manage` | Управление подписками на вебхуки                                  |
| `ingest:write`    | Массовая загрузка оргструктуры (только для супер-администраторов) |

Области — это первый рубеж. Второй — права владельца ключа: даже с областью
`employees:read` ключ видит только тех сотрудников и те поля, которые доступны
профилю прав пользователя-владельца. Эффективный доступ — пересечение областей
ключа и прав владельца.

<Tip>
  Заводите отдельный ключ под каждую интеграцию с минимально необходимым набором
  областей. При компрометации отзывается только один ключ, а не весь доступ.
</Tip>

## Жизненный цикл ключа

* **Создание.** Ключи создаёт супер-администратор в приложении:
  Настройки → Интеграции → API. Эндпоинта создания ключей в самом Developer API
  нет — ключ не может порождать другие ключи.
* **Секрет показывается один раз** — сразу при создании. Сохраните его в
  секрет-хранилище; повторно посмотреть его нельзя, в списках виден только
  префикс (`ddp_a1b2…`).
* **Отзыв.** Ключ отзывается там же, в настройках, и перестаёт работать сразу.
* **Ротация.** Создайте новый ключ с теми же областями, переключите интеграцию
  на него, затем отзовите старый. Плановая ротация раз в несколько месяцев —
  хорошая практика.
* **Права владельца — живые.** Доступ ключа вычисляется на каждый запрос по
  текущему профилю прав владельца: если права владельца сузились, сузился и
  доступ ключа.

## Редакция чувствительных полей

Поля, которые владелец ключа не вправе видеть (например ИИН), не попадают в ответ,
а их ключи перечисляются в массиве `redacted_fields` в формате `объект.поле`,
например `persons.iin`. Отсутствие поля в `redacted_fields` и пустое значение —
разные вещи: первое означает «скрыто правами», второе — «нет данных».