Личные токены

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

Ключ проекта или личный токен

Публичный API /api/v1 принимает только ключ проекта, а API кабинета — только вход: сеанс или личный токен. Интеграции проекта (CRM, бот, свой канал) подключайте ключом: он не зависит от людей и их ролей. Личный токен — для скриптов, которые делают то, что вы делаете в кабинете: выгрузки, отчёты, массовые правки, работа сразу с несколькими проектами.

Выпуск токена

1. Откройте Профиль → Личный API и нажмите «Выпустить токен». Раздел есть у каждого участника проекта: токен выпускается себе.
2. Заполните форму:
   • Название — от 1 до 100 знаков, чтобы узнать токен в списке и в письме.
   • Срок — 30 дней, 90 дней, 1 год или без срока. По умолчанию 90 дней.
   • Доступ — «Полный доступ» (чтение и запись во всех областях проектов), «Только чтение» или «Выбрать по областям».
   • Проекты — «Все мои проекты», «Выбранные» или, только у суперюзера, «Все проекты платформы».
   • Разрешённые адреса — необязательно, по одному в строке.
   • Текущий пароль — токен работает без кода 2FA, поэтому выпуск подтверждается паролем.
3. Нажмите «Выпустить» и сразу скопируйте токен. Целиком он показывается один раз: хранится только его хеш, а в списке видно начало, первые 8 знаков (shp_ и ещё четыре).

• О каждом новом токене вам приходит письмо «Создан личный API-токен»: название, области, проекты, срок, адрес и время выпуска. Самого токена в письме нет. Токен выпускали не вы — отзовите его и смените пароль. Смена пароля в профиле сама токены не гасит.
• У одного человека — не больше 25 токенов, вместе с истёкшими. Дальше выпуск отвечает 400 PERSONAL_TOKEN_LIMIT, пока вы не отзовёте ненужный.
• Неверный пароль считается неудачной попыткой входа. После 10 неудач подряд, каждая не позже 15 минут после предыдущей, вход в аккаунт и выпуск токенов закрыты, пока с последней неудачи не пройдёт 15 минут (429 AUTH_LOGIN_LOCKED), даже с верным паролем.
• Входите через SSO и не знаете пароль — задайте его через «Забыли пароль».
• Выпускают и отзывают токены только в кабинете: токеном токен не выпустить и не отозвать.
• В чужом аккаунте, куда администратор платформы вошёл из админки, выпуск закрыт. Смотреть и отзывать токены там можно.
• Enterprise Dedicated с лицензией в режиме только чтения: выпуск закрыт, отзыв работает. Токены при этом читают запросами GET и HEAD, а любой POST, PUT, PATCH и DELETE отвечает 423.

Первый запрос

Передавайте токен в заголовке Authorization со схемой Bearer:

Authorization: Bearer shp_xxxxxxxxxxxxxxxxxxxxxxxx

Пути API кабинета начинаются с /api. Почти всё, что относится к проекту, лежит под /api/w/{workspace_id}/…, где workspace_id — id проекта. Его отдаёт список ваших проектов, GET /api/workspaces/, со слешем на конце. Нужна область «Проекты» на чтение, без неё ответ — 403 PERSONAL_TOKEN_SCOPE с {"area": "projects", "need": "read"} в detail:

curl https://supporthub.cc/api/workspaces/ \
  -H "Authorization: Bearer shp_xxxxxxxxxxxx"

{
  "items": [
    { "id": "6f1c2a7e-…", "name": "Altair Cloud", "slug": "altair", "my_role": "admin", … }
  ],
  "total": 1,
  "page": 1,
  "page_size": 20,
  "pages": 1
}

Список постраничный: page и page_size (до 100). У токена с выбранными проектами в нём только они, а их id есть и в ответе GET /api/personal-tokens/current, без области «Проекты».

Дальше — запросы к проекту, например список тикетов (область «Обращения» на чтение):

curl https://supporthub.cc/api/w/<project_id>/tickets \
  -H "Authorization: Bearer shp_xxxxxxxxxxxx"

Ответ — страница тикетов в том же виде: items, total, page, page_size, pages.

Любому действующему токену, без областей, открыты три запроса:

• GET /api/personal-tokens/current — сам токен: название, области, проекты, адреса, срок, когда и откуда его использовали в последний раз
• GET /api/auth/me — чей это токен
• GET /api/openapi.json?scope=personal — эндпоинты, которые открывает токен (с lang=en — по-английски)

Токену, который не годится, все три запроса отвечают его собственной ошибкой в общем конверте: PERSONAL_TOKEN_INVALID — такого нет или он отозван, PERSONAL_TOKEN_EXPIRED — срок вышел, PERSONAL_TOKEN_IP — запрос не с разрешённого адреса.

{
  "id": "5d1e0b44-…",
  "name": "Выгрузка в CRM",
  "token_prefix": "shp_Ab3x",
  "scopes": { "tickets": "read", "contacts": "read" },
  "projects_kind": "listed",
  "workspace_ids": ["6f1c2a7e-…"],
  "allowed_ips": ["203.0.113.0/24"],
  "expires_at": "2027-02-04T09:30:00",
  "last_used_at": "2026-11-06T09:41:12",
  "last_used_ip": "203.0.113.7",
  "created_at": "2026-11-06T09:30:00"
}

Время в ответах — UTC. Тот же справочник, по областям, с моделями и примерами запросов, — во вкладке «Документация API» раздела Профиль → Личный API.

Области

Область — часть API кабинета, уровень — чтение или запись. Запись включает чтение. Чтение — это запросы GET и HEAD, запись — остальные методы. Три POST, которые ничего не меняют, считаются чтением: выгрузка журнала проекта в CSV, предпросмотр письма проекта и предпросмотр рассылки платформы. А подсказки ассистента и перевод сообщения — запись: каждый вызов расходует бюджет проекта.

Область «Админка платформы» выдаётся только администраторам платформы и никогда — токену с выбранными проектами: админка одна на всю платформу. Суперюзеру — только вместе с «Все проекты платформы».

Проекты

• Все мои проекты — проекты, где вы участник, включая те, куда вас добавят позже. Ушли из проекта — токен в нём больше не работает.
• Выбранные — только отмеченные проекты, от одного до 1000, и только те, где вы участник. Запрос к другому проекту — 403 PERSONAL_TOKEN_PROJECT.
• Все проекты платформы — только у суперюзера: любой проект платформы, как у него в кабинете.

Роль в проекте токен не меняет: оператору с токеном «Полный доступ» настройки проекта менять нельзя, как и в кабинете. Суперюзер сохраняет свои права только с токеном «Все проекты платформы». С «Все мои проекты» и «Выбранные» он на время запроса — обычный участник своих проектов, без доступа к чужим и к админке.

У маршрутов без проекта в пути, например GET /api/tickets/{ticket_id}/locate или POST /api/announcements/{ann_id}/ack, проект берётся у найденного объекта и проверяется так же.

Срок и адреса

Токен действует до конца срока: 30, 90 или 365 дней с выпуска или без срока. Продлить срок нельзя: выпустите новый токен. Истёкший токен отвечает 401 PERSONAL_TOKEN_EXPIRED и остаётся в списке с пометкой «Истёк», пока вы его не отзовёте. До тех пор он занимает место среди 25.

Разрешённые адреса необязательны: пустой список — откуда угодно. В списке — до 20 IP-адресов или подсетей, IPv4 и IPv6, например 203.0.113.7, 203.0.113.0/24, 2001:db8::/32. Подсеть хранится по адресу сети: 203.0.113.9/24 станет 203.0.113.0/24. Адрес с приставкой ::ffff: не принимается: IPv4 пишите как есть. Сверяется адрес, с которого запрос пришёл к нам: за NAT или прокси — их внешний адрес. Запрос с другого адреса — 403 PERSONAL_TOKEN_IP.

В списке токенов видно, когда и с какого адреса токен использовали в последний раз. Отметка может отставать до минуты.

Чтение без следов

Скрипт, который читает переписку, — не человек, который её прочитал. Поэтому запросы с токеном:

• не отправляют клиенту «прочитано»
• не делают тикет прочитанным у операторов
• не засчитывают просмотр статьи базы знаний
• не запускают фоновый перевод старых сообщений
• не показывают вас «в сети» посетителям виджета

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

WebSocket оператора токен не открывает. События в реальном времени отдают вебхуки и long polling публичного API, с ключом проекта.

Файлы

Файлы клиентов, то есть всё, что не приложено к внутренней заметке, отдаются по GET /api/media/{media_id} без входа, как в виджете и в почте. Файл внутренней заметки получает только участник проекта, а с токеном — ещё и с областью «Файлы» на чтение.

Такой файл никогда не подтверждает, что он есть. Любой отказ токена отвечает 404 MEDIA_NOT_FOUND, как несуществующий файл: срок вышел, токен отозван, чужой адрес, нет области «Файлы», проект не в списке токена на пути /api/w/{workspace_id}/media/…. Исключение одно: на GET /api/media/{media_id} участнику проекта, которого нет в списке токена, приходит 403 PERSONAL_TOKEN_PROJECT. Получили 404 на внутренний файл — сначала проверьте токен запросом GET /api/personal-tokens/current.

Подписанные ссылки на файлы в списке сообщений, вида …?exp=…&sig=…, открываются без токена. Храните их как секреты: кто получит такую ссылку, тот 12 часов открывает файл.

Закрыто всегда

Часть API закрыта для любого токена, какие бы области у него ни были. Токен не создаёт новый вход и ключи, не выносит секреты наружу, не меняет данные входа, свои и чужие, не выдаёт роли на платформе и владение проектом, не распоряжается деньгами, тарифами и лицензиями платформы, не удаляет проект или аккаунт. Закрыты:

• управление токенами — всё под /api/personal-tokens, кроме GET /api/personal-tokens/current
• вход, пароль, сеансы, 2FA, passkey и SSO — всё под /api/auth, кроме GET /api/auth/me, и принятие приглашения
• ключи проекта sk_…
• секреты, которые пережили бы токен: подпись токенов посетителей виджета, секретный адрес входящей почты канала, настройка модуля BILLmanager, QR привязки WhatsApp, SSO проекта
• новый оператор с паролем, передача владения проектом, удаление проекта
• действия с услугами клиентов в BILLmanager из тикета, запуск макросов, кнопки карточки клиента
• список способов оплаты и вебхуки платёжных систем, лицензия, push-подписки устройств, первый запуск установки
• в админке платформы — вход в чужой аккаунт, правка и удаление пользователей, их пароли, 2FA и passkey, их роли в проектах, письма пользователя целиком, запись настроек платформы и системных писем, сеансы поддержки, зачисление платежей, баланс и тариф проекта, правка тарифов, скидок и промокодов, выпуск и продление лицензий, перевод ботов Telegram на другой Bot API (он отдал бы токены всех ботов платформы на адрес из запроса)
• в Enterprise Dedicated — доступ поддержки, запуск обновления, домен и SMTP установки

Ответ — 403 PERSONAL_TOKEN_CLOSED, в detail.reason — closed. Если там unmapped, маршрут новый и в карту токенов ещё не внесён: до тех пор он для токенов закрыт.

Сильные действия при этом остаются в областях и открыты токену с записью в них. «Команда» меняет участникам права администратора, отключает их и убирает из проекта. «Тариф и оплата» у владельца проекта продлевает и меняет тариф за счёт баланса проекта и выставляет счета. «Админка платформы» блокирует людей, убирает их из проектов и завершает их сеансы. Запись в эти области выдавайте только скриптам, которым она нужна.

Ошибки

Ошибки токена приходят в общем конверте: error_code, error_message, detail, request_id. Формат и повторы — на странице Лимиты и ошибки.

Проверки идут по порядку: токен, срок, адрес, маршрут, область, проект. Потом маршрут проверяет вас самих, как в кабинете. Заблокированный аккаунт — 403 с {"detail": "User account has been banned."}, нет прав в проекте — те же 403 и 404, что в интерфейсе. Без заголовка Authorization ответ — 401 с {"detail": "Could not validate credentials."}.

Лимит запросов

У каждого токена своя корзина: 1000 запросов в минуту на все маршруты вместе. Процесс API помнит токен 5 минут после последнего принятого запроса с ним. Первый запрос в каждом процессе и первый после такой паузы считаются в корзину адреса клиента (тоже 1000 в минуту), как запрос без токена. При превышении приходит 429 RATE_LIMIT_EXCEEDED с заголовком Retry-After.

У отдельных маршрутов свои лимиты, строже общего, например у подсказок ассистента — 20–30 запросов в минуту. Они считаются по адресу клиента, с каким бы заголовком ни пришёл запрос.

Что гасит токен

Отозвать токен можно в разделе Профиль → Личный API: по одному или все сразу кнопкой «Отозвать все». Отозванный токен перестаёт работать сразу и отвечает 401 PERSONAL_TOKEN_INVALID. Вернуть его нельзя, только выпустить новый.

Все ваши токены отзываются сами, когда:

• пароль сбрасывают по ссылке из письма
• администратор платформы нажимает в карточке пользователя «Завершить все сессии», «Задать пароль» или «Ссылка для сброса»
• аккаунт удаляют

Смена пароля в профиле и кнопка «Завершить остальные» в сеансах токены не трогают: токены живут отдельно от сеансов. Блокировка аккаунта останавливает токены (403), после разблокировки они снова работают. Администратор платформы видит ваши токены в карточке пользователя, только их начало, и может отозвать любой.