> ## 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.
# Безопасность
> Хранение ключа, модель доступа, требования к адресу вебхука
## Ключ
Ключ Developer API даёт доступ к данным всего тенанта в пределах своих областей и
прав владельца. Обращайтесь с ним как с паролем сервиса.
* Храните в секрет-хранилище или переменной окружения, не в репозитории и не в
конфиге рядом с кодом.
* Никогда не используйте во фронтенде и мобильном приложении: там его увидит
любой пользователь.
* Заводите отдельный ключ на каждую интеграцию. При компрометации отзывается
один ключ, а не весь доступ.
* Ротация — ручная: создайте новый ключ, переключите интеграцию, затем отзовите
старый. Срока действия у ключей сейчас нет.
* Секрет показывается один раз при создании. В списках виден только префикс из
12 символов.
Не логируйте значение ключа и не подставляйте его в примеры, которые уходят в
трекер задач или в чат. Если ключ мог утечь — отзовите его в настройках, это
действует немедленно.
## Что видит ключ
Эффективный доступ — это пересечение двух ограничений:
1. **Области ключа.** Эндпоинт требует конкретную область; без неё запрос
отклоняется с `DEVELOPER.SCOPE_INSUFFICIENT`.
2. **Права владельца ключа.** Ключ видит ровно тех сотрудников, те документы и те
поля, которые доступны профилю прав пользователя, создавшего ключ. Права
вычисляются на каждый запрос: сузили права владельцу — сузился доступ ключа.
Отсюда два следствия. Чувствительные поля, недоступные владельцу, в ответ не
попадают, а их имена перечисляются в `redacted_fields`. Недоступный одиночный
ресурс неотличим от несуществующего: и то и другое возвращает `404`.
Ключ перестаёт работать, когда владельца исключают из тенанта или деактивируют
его учётную запись, — отдельно отзывать ключ при увольнении не требуется, но
проверить список ключей после ухода сотрудника стоит.
## Адрес вебхука
Doodocs сам обращается к вашему серверу, поэтому к адресу подписки предъявляются
требования:
* только схема `https`;
* только публично разрешимый адрес: `localhost`, приватные диапазоны и служебные
адреса облаков отклоняются с кодом `DEVELOPER.WEBHOOK_URL_INVALID`.
Для локальной отладки поднимайте туннель с публичным `https`-адресом.
## Проверка доставки
Каждая доставка подписана: заголовок `Doodocs-Signature` несёт метку времени и
HMAC-SHA256 от `{t}.{тело}` с секретом подписки. Проверяйте подпись до разбора
тела и отклоняйте запросы старше пяти минут — иначе перехваченную доставку можно
будет воспроизвести.
Секрет показывается один раз при создании подписки и не ротируется. Чтобы его
сменить, создайте новую подписку с тем же адресом и набором событий, переключите
проверку на новый секрет и удалите старую.
Полезная нагрузка события намеренно тонкая: тип, время и идентификатор ресурса.
Персональные данные на внешний адрес не уходят — их вы забираете обычным
запросом со своим ключом, и к ним применяются области и редакция полей.
События по документам доставляются по всем документам тенанта, на которые
подписан эндпоинт, независимо от прав владельца ключа. Само событие несёт только
идентификатор и время; содержимое документа по-прежнему закрыто правами при
чтении через `GET /documents/{id}`.