Аутентификация
Каждый запрос к /v1 аутентифицируется. Из собственных систем проходите
аутентификацию с персональным токеном доступа (PAT), передаваемым как
bearer-токен:
Authorization: Bearer waafir_pat_…Выпускайте, ограничивайте и отзывайте токены в разделе Дополнения → Конфигурация. Руководство по персональным токенам доступа описывает выпуск, срок действия (по умолчанию 90 дней, максимум 365), однократный показ и отзыв. Эти правила одинаковы и для Platform API. На этой странице описано, что может делать токен, когда он у вас уже есть.
Персональный токен доступа действует от имени человека, который его выпустил, внутри организации этого человека. Ни в одном URL или теле запроса нет параметра организации, поскольку токен уже однозначно её определяет.
Три проверки токена
Запрос, аутентифицированный токеном, должен пройти эти три проверки, помимо
прочих. Политика безопасности организации и собственные проверки эндпоинта
также могут его отклонить (см. ниже). У двух из трёх есть собственный код. Отказ по
роли может вернуть FORBIDDEN, общий и для других отказов, поэтому читайте
код вместе с требованиями эндпоинта.
| Проверка | Вопрос | Отказ |
|---|---|---|
| Область действия токена | Покрывает ли область действия токена то, что делает этот эндпоинт? | PAT_SCOPE_INSUFFICIENT 403 |
| Роль | Есть ли у вызывающего роль, которую требует этот эндпоинт? | FORBIDDEN 403 или PAT_ROLE_CEILING 403 |
| Комната данных | Для токена, ограниченного комнатами данных: есть ли эта комната данных в его списке? | PAT_DATAROOM_SCOPE 403 |
Области действия токена
Токен имеет одну область действия: read, write или admin — в порядке
возрастания полномочий. Более высокая область включает всё, что ниже неё.
Область, которая нужна эндпоинту, по умолчанию определяется его HTTP-методом:
GET,HEADиOPTIONSтребуютread.- Все остальные методы (
POST,PATCH,PUT,DELETE) требуютwrite.
Некоторые эндпоинты объявляют другую область. Обычный случай — POST, который
только выполняет запрос и требует лишь read.
Справочник эндпоинтов показывает область,
которую фактически требует каждый эндпоинт, поэтому проверяйте её там, а не
выводите из метода.
Требуемая роль и потолок роли
Область действия определяет, что может делать токен. Требуемая роль
эндпоинта определяет, кем должен быть человек. Многие эндпоинты /v1
требуют принадлежности к команде сделки (владелец, администратор или участник
организации). Изменения в команде и в предоставленном доступе, среди прочего,
требуют владельца или администратора. У инвесторов и других гостей нет роли в
команде сделки, поэтому эндпоинты команды сделки им отказывают. Другие
эндпоинты не объявляют ограничения по роли на уровне аутентификации и вместо
этого проверяют доступ внутри эндпоинта. Например, маршруты мониторинга
портфеля проверяют дополнение «Мониторинг» и доступ вызывающего к мониторингу.
Справочник эндпоинтов показывает ограничение
по роли для каждого эндпоинта. Если оно не объявлено, учитывайте, что сам
эндпоинт всё равно может отказать.
Токен также фиксирует роль выпустившего его человека на момент выпуска в
качестве потолка. Waafir применяет меньшую из двух ролей: текущую роль
выпустившего и этот потолок. Участник, которого позже повысили до
администратора, по-прежнему действует как участник через токен, выпущенный
ранее; чтобы использовать новую роль, выпустите новый токен. Человек, роль
которого понизили, теряет полномочия немедленно, что бы ни было зафиксировано в
токене. В обоих случаях запрос отклоняется с 403 как FORBIDDEN или
PAT_ROLE_CEILING.
Токены, ограниченные комнатами данных
Токен, выпущенный с выбором конкретных комнат данных вместо варианта Все комнаты данных, даёт доступ только к этим комнатам. Запрос, в котором
указана любая другая комната данных, отклоняется с PAT_DATAROOM_SCOPE.
Некоторые эндпоинты уровня всей организации полностью отклоняют ограниченный
токен с тем же кодом, поскольку их ответ охватывает комнаты данных, которые
токен не видит. Для них используйте неограниченный токен.
GET /api/v1/session принимает оба вида.
Другие отказы, которые могут встретиться
401 UNAUTHORIZED: нет заголовкаAuthorizationлибо токен неизвестен, истёк или отозван.404для ресурса другой организации. Идентификатор, принадлежащий другой организации, обрабатывается как не найденный, поэтому его существование не подтверждается.- Нет приоритета владельца/администратора для файлов с ограниченным доступом. В приложении владелец или администратор организации видит каждый
файл с ограниченным доступом. Токен — нет: он получает доступ к такому файлу,
только если его владелец создал этот файл или имеет на него предоставленный
доступ. Запрос, указывающий файл, который токен не может прочитать, получает
тот же ответ, что и запрос к отсутствующему файлу (для
/api/v1/grants—400с указанием файла или404для предоставленного доступа), с сообщением о том, что он «not found, or not readable by this credential», поэтому ответ никогда не подтверждает существование файла. - Политика безопасности организации. Если в вашей организации настроен
список разрешённых IP-адресов, запрос извне него получает ответ
IP_BLOCKED. Принудительная двухфакторная аутентификация может вернутьMFA_SETUP_REQUIREDилиMFA_CHALLENGE_REQUIRED. 429 RATE_LIMITED. Некоторые эндпоинты объявляют поминутный лимит для каждой личности, указанный у эндпоинта. Остальные используют лимит платформы по умолчанию. Сделайте паузу и повторите попытку.
Страница кодов ошибок перечисляет известные коды и их значения.