Токены и доступ по API
Токен — доступ к приложению для программы: выгрузки, бота, скрипта. Он ходит в приложение вместо вас и умеет только то, что умеете вы, — или меньше.
Если автоматизация не нужна, эта страница вам не понадобится: всё, что делает токен, можно делать руками в приложении.
Кто может выдать
Заголовок раздела «Кто может выдать»Токен выдают себе сами — в разделе «Профиль», пункт
«Токены автоматизации». Нужно право «Выдавать себе токены автоматизации»
(tokens:issue); в стандартных ролях оно есть у владельца.
Чужие токены — отдельное право tokens:manage: с ним видно и можно отозвать
токены коллег. Полный список прав — в разделе
«Права доступа».
Как выдать
Заголовок раздела «Как выдать»Откройте «Токены автоматизации» и нажмите «Выдать токен».
Зачем выдан — имя, по которому через полгода будет понятно, что отзывать. Оно обязательно и видно в списке.
Где работает — салоны. Можно отметить несколько или выбрать «во всех моих салонах». В каждом салоне нужно право выдавать токены, и больше своих прав в этом салоне выдать нельзя. Токен, выданный в салоне, виден администратору этого салона — и он же может его отозвать.
Срок — 30 дней, 90 дней, год или бессрочно. Бессрочный живёт, пока его не отзовут; для автоматизации это нормально.
Что разрешить — список ваших прав в выбранных салонах. Отмечайте только то, что программе действительно нужно. Ничего не отметите — токен будет видеть своё и ничего не менять; для выгрузок этого часто достаточно.
Значение показывается один раз
Заголовок раздела «Значение показывается один раз»
Запишите значение сразу. На сервере хранится только его отпечаток, и показать второй раз его нечем — потеряли значит потеряли: остаётся отозвать токен и выдать новый.
Значение начинается с pcat_. Приставка нужна, чтобы утёкшая строка была
узнаваема как ключ доступа — и человеком в чужом конфиге, и программами,
которые ищут секреты в репозиториях.
Список и отзыв
Заголовок раздела «Список и отзыв»
У каждого токена видно, зачем он выдан, до какого числа действует, что ему разрешено, в каких салонах и когда он работал в последний раз. Последнее помогает понять, пользуется ли кто-то токеном вообще, — и спокойно отозвать тот, которым не пользуются.
«Отозвать» закрывает доступ сразу. Отозванный токен остаётся в списке серой строкой: это запись о том, что доступ выдавался, и терять её незачем.
Права выданного токена не меняются — кнопки «изменить» нет, и это не упущение. У секрета, который уже лежит в чужом конфиге, права не правят: его отзывают и выдают новый.
Что происходит с правами потом
Заголовок раздела «Что происходит с правами потом»Права токена всегда пересекаются с вашими текущими. Если у вас забрали право, токен теряет его в ту же минуту — даже если при выдаче оно было отмечено и в списке осталось.
Из этого следует неприятное, но честное: увольнение человека обесценивает его токены. Если автоматизация должна пережить смену сотрудника, заводите её на того, кто не уйдёт, — или будьте готовы перевыпустить токен.
Как обращаться по API
Заголовок раздела «Как обращаться по API»Токен передаётся заголовком:
Authorization: Bearer pcat_ваше_значениеЧто отвечает приложение на неудачу:
| Ответ | Что случилось |
|---|---|
401 |
токена нет, он отозван или истёк |
403 |
токену не хватает права на это действие |
Какие есть ручки, какие у них параметры и что они возвращают — в разделе «API». Там же примеры запросов, которые можно скопировать.