Skip to main content

​
Ключ

Ключ 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}.