О легаси-токенах и OAuth-приложениях

В группе Админ → API и доступы лежат два вида токенов: легаси-токены на экране Токены аутентификации и токены OAuth-приложений на экране Приложения OAuth. Легаси-токены появились раньше и остаются ради интеграций, которые на них построены. Новые интеграции Aplaut рекомендует строить на OAuth-приложениях.

Чем неудобен легаси-токен

Легаси-токен один на API и на всю компанию. Его создаёт платформа вместе с компанией. Срока действия у него нет, а в кабинете его нельзя ни перевыпустить, ни отозвать.

Пока токеном пользуется одна интеграция, это незаметно. Проблемы начинаются, когда интеграций несколько: сайт, выгрузка в CRM, скрипт подрядчика. Все они ходят с одним и тем же токеном, и по запросу нельзя понять, какая из них его отправила. Если подрядчик закончил работу или токен попал в открытый репозиторий, закрыть ему доступ можно только вместе с остальными интеграциями. В кабинете даже этого сделать нельзя.

Что меняет OAuth-приложение

OAuth-приложение — отдельный пропуск для одной интеграции. Из этого следуют четыре свойства, которых нет у легаси-токена.

Первое — ограниченный доступ. Токен получает только те API, которые отмечены в блоке Возможности. Токену виджетов на сайте хватает доступов для виджетов 2.0, и выгрузить с ним данные аккаунта через Platform API не получится. Для виджетов 2.0 это особенно важно: их токен стоит в коде страницы, и увидеть его может любой посетитель.

Второе — отзыв по одному. Утёкший или ненужный токен отзывается, а остальные интеграции продолжают работать.

Третье — срок 2 года. Забытый токен перестаёт работать сам, а не остаётся открытым доступом навсегда. Цена этого — плановая замена раз в два года. Чтобы заменить токен без простоя, у приложения может быть несколько действующих токенов одновременно.

Четвёртое — название. По списку приложений видно, какие интеграции вообще существуют и у кого какой доступ.

Почему доступы и токен нельзя изменить после выдачи

Токен получает набор доступов приложения в момент генерации и хранит его у себя. Если бы набор у приложения можно было поменять, в кабинете стояли бы одни доступы, а уже выданные токены работали бы с прежними. Поэтому набор фиксируется при создании, а для другого набора создаётся новое приложение.

Полный токен виден один раз, в окне Новый токен, а дальше в списке остаются шесть последних символов. Так человек с доступом к кабинету не может позже скопировать токен, который уже работает в интеграции. Шести символов достаточно, чтобы сверить, какой токен где стоит.

Где легаси-токен пока нужен

Platform API v4 и Submissions API v2 принимают оба вида токенов в одном и том же заголовке Authorization. Чтобы перевести такую интеграцию на OAuth, достаточно подставить новый токен, формат запросов не меняется. Именно у этих двух строк на экране Токены аутентификации стоит пометка «(легаси)».

Widgets API v2 токены OAuth-приложений не принимает, и пометки «легаси» у него нет. Интеграция с собственными виджетами через Widgets API v2 работает только с легаси-токеном. Виджеты 2.0 устроены иначе: они с самого начала работают с токеном OAuth-приложения.

Как выдать и заменить токен — см. как получить токен доступа к API. Доступы, сроки и способы передачи токена — в справочнике группы «API и доступы».