Личные токены доступа
Личный токен доступа (Personal Access Token, PAT) — это учётные данные, которые вы создаёте и вставляете сами. Он предназначен для REST API Waafir и скриптов, а также для ИИ-помощника, который не может выполнить вход: большинство помощников подключаются вставкой URL Waafir и входом в систему, вовсе без токена. На MCP-серверах Waafir каждый запрос несёт либо подключение, созданное при входе, либо действительный PAT. Анонимного доступа нет, а обычный сеанс браузера с выполненным входом на этой поверхности не принимается (запрос, аутентифицированный сеансом, отклоняется). PAT действует от вашего имени в пределах вашей организации и ограничен областью доступа и комнатами данных, которые вы выбираете при его выпуске.
Где выпустить токен
Откройте Дополнения → Конфигурация → API-токены. Страница состоит из трёх частей: формы для выпуска нового токена, списка ваших существующих токенов (с действием отзыва) и готового к использованию фрагмента конфигурации для подключения помощника с помощью токена.
Чтобы выпустить токен, заполните форму:
- Имя — понятная человеку метка, по которой вы позже узнаете токен (например, «Claude Desktop – ноутбук»). Обязательное поле.
- Область доступа — что разрешено делать токену. См. ниже.
- Область комнаты данных — оставьте флажок Все комнаты данных, чтобы токен имел доступ ко всем комнатам данных, доступным вам, или снимите его и выберите конкретные комнаты данных, чтобы ограничить токен только ими.
- Срок действия — дата, после которой токен перестаёт работать. Заполнять это поле необязательно, но по сути оно обязательно: если оставить его пустым, токен выпускается со сроком действия 90 дней. См. Срок действия.
Области доступа
Токен несёт одну из трёх областей доступа, в порядке возрастания полномочий:
| Область доступа | Разрешает | Типичное применение |
|---|---|---|
read | Просмотр списков и чтение — комнаты данных, папки, файлы, метаданные файлов, поиск, URL для скачивания и просмотр разрешений; чтение извлечённого текста документа; чтение веток вопросов и ответов инвесторов; проверка статуса задания скрытия данных, перевода или электронной подписи. | Помощник только для чтения, который отвечает на вопросы о комнате данных. |
write | Всё, что разрешает read, плюс изменения: создание, переименование, перемещение, удаление и восстановление папок; загрузка, переименование, перемещение, удаление и восстановление файлов, включая загрузку новой версии файла и откат к прежней; запуск скрытия данных или перевода документа; а также создание, отправка, отклонение и аннулирование конвертов электронной подписи. Для отправки конверта (или добавления подписантов в уже отправленный) также нужно разрешение Отправлять людям вне вашей организации, и помощник просит вас подтвердить отправку. Для подписания (esign_sign) также нужно разрешение Подписывать документы, и оно тоже сначала подтверждается. | Помощник, который упорядочивает или поддерживает комнату данных. |
admin | Всё, что разрешает write, плюс четыре инструмента предоставления разрешений: предоставление или отзыв доступа пользователя к файлам и комнатам данных. Обратите внимание, что трём инструментам чтения разрешений достаточно read. | Помощник, который управляет тем, кто что может видеть. |
Области доступа накопительны — более высокая область включает всё, что ниже. В справочнике инструментов каждого сервера указана минимальная область доступа, необходимая для каждого инструмента.
Кто может выпускать каждую область доступа
Токен никогда не может нести больше полномочий, чем у человека, который его выпускает:
readиwriteможет выпустить любой активный участник вашей организации.adminможет выпустить только владелец или администратор организации. Если вы не владелец и не администратор, вариантadminне появляется в селекторе области доступа.- Инвесторы (и другие роли вне команды сделки) вообще не могут выпускать токены.
Помимо выпуска, инструменты разрешений уровня admin применяют второе
ограничение в момент вызова: для успешного предоставления разрешения владелец
токена сам должен быть администратором или менеджером в организации. Область
доступа токена — это потолок токена; роль владельца — потолок человека, и
административное действие должно пройти оба — ровно то же правило, что
применяет интерфейс продукта. Через MCP нет более свободного пути, чем через
продукт.
Разрешение токену подписывать документы
Для подписания нужен токен с включённым параметром Подписывать документы. Вы
выбираете его при создании токена в разделе Дополнения → Конфигурация для
токена write или admin, чтобы подписывать за вас мог только помощник,
которому вы доверились. Создание токена уже запрашивает ваш код двухфакторной
аутентификации, если она у вас включена, поэтому эта проверка распространяется
на каждую подпись, сделанную токеном. В списке токенов у каждого такого токена
отображается Может подписывать.
Помощник сначала показывает вам документы, подписанта и поля и подписывает
только после вашего подтверждения. Токену без Подписывать документы не
показывается esign_sign в списке инструментов, а при вызове он отклоняется.
Токены, созданные до появления этого параметра, не могут подписывать: создайте
новый с включённым параметром Подписывать документы.
Разрешение токену читать содержимое документов
Для чтения документа целиком или вопросов к ИИ о документах нужен токен с включённым параметром Читать содержимое документа. Вы выбираете его при создании токена в разделе Дополнения → Конфигурация, при любой области доступа. В списке токенов у каждого такого токена отображается Содержание документа. Он распространяется на:
get_file_text— полный извлечённый текст документа;get_file_download_url— ссылку для скачивания файла;esign_download_signed— подписанный PDF электронной подписи;- ссылку для скачивания, которую
translate_file_statusвозвращает для завершённого перевода; GET /api/v1/files/{fileId}/content— байты документа через REST API;POST /api/viewer/token,POST /api/viewer/artifact-accessиPOST /api/viewer/artifact-access/unlock, которые выпускают токен просмотрщика или cookie, по которым встроенный в продукт просмотрщик документов передаёт документ;- ИИ-инструменты, вопрос или входные данные для которых пишете вы, поскольку
ответ может повторять содержание документа:
dataroom_ask,dataroom_draft_answer,dataroom_compare_filesиdataroom_generate_update; POST /api/v1/chat— тот же ответ ИИ через REST API;quoteкаждого факта, который возвращаетGET /api/v1/facts.
Токену без этого параметра в этих инструментах отказывается (GRANT_REQUIRED)
и в этих REST-маршрутах тоже (PAT_GRANT_REQUIRED), а translate_file_status
вместо ссылки возвращает статус с download_withheld_reason: content_grant_required.
GET /api/v1/facts и dataroom_list_facts возвращают каждый факт без его
quote, при этом value сокращается до 20 слов и устанавливается
value_truncated. Токен по-прежнему может просматривать списки и выполнять
поиск, а также читать сводку документа с помощью get_file_metadata или
dataroom_summarise_file. Токены, созданные до появления этого параметра, не
могут читать содержимое документов: создайте новый с включённым параметром
Читать содержимое документа. На сервисные токены это не влияет.
Каждый токен может получать не более 10 ссылок для скачивания в минуту. Сверх
этого get_file_download_url отклоняется (RATE_LIMITED), а
translate_file_status возвращает статус с
download_withheld_reason: rate_limited; повторите запрос через минуту.
Разрешение токену отправлять людям вне вашей организации
Создание ссылки для общего доступа, добавление зрителя снимка, приглашение
участника команды или инвестора, а также продление или восстановление доступа
инвестора (dataroom_extend_investor_access, dataroom_reinstate_investor_access)
передают доступ человеку вне вашей организации, поэтому для них нужен токен с
включённым параметром Отправлять людям вне вашей организации (то же
разрешение, что отправляет обновления для инвесторов, ответы на вопросы и
запросы электронной подписи). Вы выбираете его при создании токена write
или admin в разделе Дополнения → Конфигурация. В списке токенов у каждого
такого токена отображается Может отправлять за пределы.
Помощник сначала показывает вам, кого допускает новая ссылка, правило NDA и срок действия, и создаёт её только после вашего подтверждения. Для отзыва ссылки или зрителя разрешение не нужно.
Разрешение также распространяется на предоставление человеку вне вашей
команды сделки (владельцы, администраторы и участники) доступа или
расширенного доступа к комнате или документу. «Вне» означает любого, кто не
является активным участником команды сделки организации, которой принадлежит
комната: инвесторов, гостей, людей с ожидающим приглашением и участников
другой организации. Без этого разрешения токену отказывается
(GRANT_REQUIRED в MCP) в следующем:
- предоставление такому человеку права на чтение или скачивание:
set_file_permissions,dataroom_set_folder_permissions,dataroom_bulk_set_file_permissions; - снятие запрета для такого человека, которое восстанавливает его доступ:
revoke_file_permission,dataroom_revoke_folder_permission,dataroom_bulk_revoke_file_permissions; - доступ к комнате для такого человека на любом уровне:
invite_user_to_dataroom; - изменение роли участника, текущая роль которого не относится к команде
сделки, что повышает его:
dataroom_team_change_member_role; - изменение для инвестора, расширяющее доступ:
dataroom_set_investor_permissionsс переходом от зрителя к скачивающему, отключением NDA или включением мониторинга или обновлений.
Запреты, прекращение доступа и предоставление доступа вашей команде сделки разрешения не требуют. Содержимое, размещённое там, где у человека уже есть доступ (загрузка, перемещение, публикация), этим не охватывается. Для прикрепления NDA фирмы, подписанного этой фирмой, разрешение не нужно.
То же разрешение применяется к следующим REST-вызовам, выполняемым с личным токеном доступа:
POST /api/share-links(создание ссылки) иPOST /api/snapshots/{id}/viewersбез него отклоняются с403 PAT_GRANT_REQUIRED;POST /api/investors/invite(создаёт персональную ссылку и отправляет её по электронной почте) отклоняется так же;PATCH /api/investors/{id}/extendиPATCH /api/investors/{id}/access(восстановление доступа инвестора или одобрение запроса на доступ) отклоняются так же; для отзыва доступа инвестора (DELETE /api/investors/{id}/access) разрешение не нужно;POST /api/team,POST /api/v1/teamиPOST /api/team/resend(приглашение в команду отправляет по электронной почте ссылку для присоединения) отклоняются так же;PATCH /api/share-links/{id}отклоняется при любом изменении настроек доступа ссылки (её включение, режим, домены, срок действия или NDA — независимо от того, расширяет изменение доступ или сужает); отключение ссылки разрешено всегда;GET /api/share-linksотвечает безurlиtokenкаждой ссылки, помечая ихurlWithheld: true, сurlWithheldReason, объясняющим причину;POST /api/v1/grantsотклоняется для права на чтение или скачивание для человека вне команды сделки;DELETE /api/v1/grants/{id}отклоняется, если это право — запрет для такого человека;PATCH /api/v1/team/{id}отклоняется, если текущая роль участника не относится к команде сделки.
Эти проверки читают путь так, как его маршрутизирует сервер, поэтому
завершающая косая черта или символ в процентной кодировке не позволяют их
обойти. Путь, который невозможно декодировать или который содержит сегмент
./.. или закодированный / внутри сегмента, не может быть сопоставлен ни
с одним из вызовов, охватываемых разрешением. Поэтому у личного токена
доступа, которому не хватает любого разрешения на уровне запроса — этого,
Читать содержимое документа или
Читать аналитику взаимодействия, — каждый
такой путь отклоняется с 403 PAT_PATH_MALFORMED, каким бы ни был вызов.
Токены, созданные до появления этого разрешения, его не имеют, поэтому они
теряют доступ к этим вызовам, пока вы не создадите новый токен write или
admin с включённым параметром. Токен read не может иметь это разрешение.
Разрешение токену читать аналитику взаимодействия
Читать аналитику взаимодействия позволяет токену видеть, кто просматривал какие документы, когда и как долго: инструменты взаимодействия и данные о взаимодействии в реестре инвесторов. Включайте его только для помощника, который должен это видеть. Его может иметь токен с любой областью доступа.
То же разрешение применяется к REST-запросам на чтение активности:
GET /api/v1/activity (лента активности и аудита организации),
/api/v1/activity/rollups, /api/v1/activity/engagement,
/api/v1/activity/engagement/documents и
/api/v1/activity/engagement/document/pages. Без него личному токену доступа
отказывается с 403 PAT_GRANT_REQUIRED. На сервисные токены и сеансы с
выполненным входом это не влияет.
Токены, созданные до появления этих параметров, не имеют ни одного из них: создайте новый с включённым параметром.
Ограничение токена конкретными комнатами данных
По умолчанию токен имеет доступ ко всем комнатам данных, доступным его владельцу. Если снять флажок Все комнаты данных и выбрать конкретные комнаты, токен ограничивается этим списком разрешённых: любой вызов инструмента, ссылающийся на комнату данных вне списка, отклоняется, а токен с ограниченной областью даже не видит названий комнат данных, которые не может открыть. Используйте это, чтобы дать ИИ-клиенту доступ к одной сделке, не раскрывая остальной портфель.
Срок действия
У каждого токена есть срок действия. Бессрочных PAT не бывает: токен без срока действия сам по себе был той уязвимостью, которую закрывает это поведение, потому что забытые учётные данные остаются действительными вечно. Если задать дату окончания срока действия, токен перестаёт работать после этой даты — запрос с истёкшим токеном отклоняется точно так же, как с отозванным, с HTTP 401.
- Оставьте поле пустым — и вы получите 90 дней, отсчитываемых с момента выпуска токена. Пустое поле означает использовать значение по умолчанию, а не никогда не истекать.
- Задайте дату — и она будет соблюдена в точности, но не более чем на 365 дней с момента выпуска.
- Если запросить больше 365 дней, запрос отклоняется, а не сокращается втихую — при выпуске вам никогда не выдадут токен с более коротким сроком, чем вы просили, не сообщив об этом. Дата в прошлом отклоняется так же.
Поэтому, если интеграция должна работать и дальше, задавайте срок действия осознанно и поставьте в календаре напоминание заменить токен до его истечения — пустое поле молча остановит эту интеграцию примерно через три месяца после настройки. Для существующего токена нет действия продления или ротации и нет предупреждения перед истечением срока: замена означает выпуск нового токена, обновление конфигурации клиента и отзыв старого. И наоборот, короткий срок действия — именно то, что нужно для токена, выпускаемого для разовой задачи.
Список токенов в разделе Дополнения → Конфигурация показывает срок действия каждого токена, чтобы вы видели, какие из них скоро истекут.
Однократный показ
При выпуске токена его исходное значение — оно начинается с waafir_pat_ —
показывается ровно один раз, сразу после создания. Waafir никогда не
хранит исходный токен, а только его односторонний хеш, поэтому его нельзя восстановить или показать снова.
- Скопируйте его сейчас и сразу вставьте в конфигурацию клиента. На панели показа есть кнопка копирования.
- Если вы его потеряете, восстановить его нельзя — отзовите этот токен и выпустите новый.
- Обращайтесь с ним как с паролем: он предоставляет свою область доступа любому, у кого он есть.
После показа список токенов отображает только короткий несекретный префикс
(например, waafir_pat_ab12…), чтобы вы могли различать токены, не имея
возможности восстановить секрет.
Отзыв токена
В списке токенов в разделе Дополнения → Конфигурация используйте действие Отозвать рядом с нужным токеном. Отзыв происходит немедленно — следующий запрос с этим токеном отклоняется. Отзывайте токен сразу же, как только потеряно устройство, уходит подрядчик или доступ просто больше не нужен. Отозванные токены остаются видимыми в списке (с пометкой об отзыве), чтобы сохранялась запись о том, что существовало; повторно активировать их нельзя.
Когда токен прекращает действие сам
Токен действует через ваше членство в организации, поэтому он прекращает действие вместе с этим членством. Вам не нужно отзывать его самостоятельно, когда:
- Вы покидаете организацию или администратор удаляет вас. Все ваши токены в этой организации отзываются в тот же момент. Токены в других организациях продолжают работать.
- Администратор Waafir удаляет вашу учётную запись. Ваши токены во всех организациях отзываются.
- Администратор Waafir удаляет организацию. Все токены в ней отзываются, включая её сервисные токены.
Эти отзывы необратимы. Повторное приглашение или восстановление вашей учётной записи либо организации не возвращает токен: выпустите новый.
Сервисный токен принадлежит организации, а не администратору, который его создал, поэтому он продолжает работать после ухода этого администратора. Досрочно его прекращает только отзыв или удаление организации.
История токенов в журнале аудита
Каждый выпуск или отзыв токена записывает строку в журнал аудита организации: кто это сделал, имя токена, область доступа, разрешения и срок действия, сколькими комнатами данных он ограничен и почему он был отозван (владельцем, из-за прекращения членства или из-за удаления учётной записи или организации). Сам токен, его хеш и префикс никогда не записываются. Строки отображаются в полной ленте активности, а не в сводке на панели управления.
Если Waafir не может записать новый токен в журнал аудита, токен не выпускается, и вы видите сообщение «Токен не был создан, потому что нам не удалось его записать. Попробуйте ещё раз.»
Далее: настройте клиент с только что выпущенным токеном.