Перейти к содержимому

Токены и доступ по API

Токен — доступ к приложению для программы: выгрузки, бота, скрипта. Он ходит в приложение вместо вас и умеет только то, что умеете вы, — или меньше.

Если автоматизация не нужна, эта страница вам не понадобится: всё, что делает токен, можно делать руками в приложении.

Токен выдают себе сами — в разделе «Профиль», пункт «Токены автоматизации». Нужно право «Выдавать себе токены автоматизации» (tokens:issue); в стандартных ролях оно есть у владельца.

Чужие токены — отдельное право tokens:manage: с ним видно и можно отозвать токены коллег. Полный список прав — в разделе «Права доступа».

Откройте «Токены автоматизации» и нажмите «Выдать токен».

Форма выдачи токена: имя, салоны, срок и список прав с галочками
Та же форма на телефоне

Зачем выдан — имя, по которому через полгода будет понятно, что отзывать. Оно обязательно и видно в списке.

Где работает — салоны. Можно отметить несколько или выбрать «во всех моих салонах». В каждом салоне нужно право выдавать токены, и больше своих прав в этом салоне выдать нельзя. Токен, выданный в салоне, виден администратору этого салона — и он же может его отозвать.

Срок — 30 дней, 90 дней, год или бессрочно. Бессрочный живёт, пока его не отзовут; для автоматизации это нормально.

Что разрешить — список ваших прав в выбранных салонах. Отмечайте только то, что программе действительно нужно. Ничего не отметите — токен будет видеть своё и ничего не менять; для выгрузок этого часто достаточно.

Экран после выдачи: значение токена, кнопки «Скопировать» и «Записал, закрыть»
Тот же экран на телефоне

Запишите значение сразу. На сервере хранится только его отпечаток, и показать второй раз его нечем — потеряли значит потеряли: остаётся отозвать токен и выдать новый.

Значение начинается с pcat_. Приставка нужна, чтобы утёкшая строка была узнаваема как ключ доступа — и человеком в чужом конфиге, и программами, которые ищут секреты в репозиториях.

Список токенов: действующий со сроком и правами, отозванные ниже
Тот же список на телефоне

У каждого токена видно, зачем он выдан, до какого числа действует, что ему разрешено, в каких салонах и когда он работал в последний раз. Последнее помогает понять, пользуется ли кто-то токеном вообще, — и спокойно отозвать тот, которым не пользуются.

«Отозвать» закрывает доступ сразу. Отозванный токен остаётся в списке серой строкой: это запись о том, что доступ выдавался, и терять её незачем.

Права выданного токена не меняются — кнопки «изменить» нет, и это не упущение. У секрета, который уже лежит в чужом конфиге, права не правят: его отзывают и выдают новый.

Права токена всегда пересекаются с вашими текущими. Если у вас забрали право, токен теряет его в ту же минуту — даже если при выдаче оно было отмечено и в списке осталось.

Из этого следует неприятное, но честное: увольнение человека обесценивает его токены. Если автоматизация должна пережить смену сотрудника, заводите её на того, кто не уйдёт, — или будьте готовы перевыпустить токен.

Токен передаётся заголовком:

Authorization: Bearer pcat_ваше_значение

Что отвечает приложение на неудачу:

Ответ Что случилось
401 токена нет, он отозван или истёк
403 токену не хватает права на это действие

Какие есть ручки, какие у них параметры и что они возвращают — в разделе «API». Там же примеры запросов, которые можно скопировать.