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

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

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

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

Ключ несёт набор областей. Ручка требует конкретную область, и ключ должен ею обладать, иначе запрос отклоняется с DEVELOPER.SCOPE_INSUFFICIENT (HTTP 403). Области — это первый рубеж. Второй — права владельца ключа: даже с областью employees:read ключ видит только тех сотрудников и те поля, которые доступны профилю прав пользователя-владельца. Эффективный доступ — пересечение областей ключа и прав владельца.
Заводите отдельный ключ под каждую интеграцию с минимально необходимым набором областей. При компрометации отзывается только один ключ, а не весь доступ.

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

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

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

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