Аутентификация и права

Как устроены ключи, области доступа и что делать, если ключ перестал работать.

Ключ в заголовке

Каждый запрос несёт ключ в стандартном заголовке:

Authorization: Bearer tygy_AbCdEfGhIjKlMnOpQrStUvWxYz0123456789abcd

Ключи российских проектов начинаются с tygy_, международных — с tgdesk_. Префикс нужен, чтобы утёкший ключ можно было опознать по одному взгляду и найти поиском в логах.

Сессия кабинета и ключ API — разные вещи. Ключ не работает на внутренних адресах, а сессия не работает на /v1/. Это сделано намеренно.

Области доступа

Ключ несёт список прав в форме ресурс:действие. Каждый метод в справочнике называет то право, которое ему нужно.

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

1. Чтение никогда не даёт права менять. conversations:read не позволит закрыть диалог.
2. Изменение не даёт права писать клиенту. conversations:write меняет статусы и теги, но отправка сообщения требует отдельного messages:send.
3. Ключ не может получить больше, чем есть у создателя. Администратор, у которого нет права отвечать клиентам, не выдаст ключу messages:send.

Если прав не хватает

Ответ 403 называет недостающее право — не нужно гадать:

{
  "error": {
    "code": "insufficient_scope",
    "message": "This endpoint requires the \"messages:send\" scope",
    "details": { "required_scope": "messages:send" },
    "request_id": "5f0f…"
  }
}

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

Если ключ не работает

Ответ 401 означает, что ключ мёртв. Мы намеренно не уточняем, почему именно: отозван, истёк срок или такого ключа никогда не было — снаружи это выглядит одинаково, чтобы перебор ключей не приносил информации.

Проверьте по порядку:

• ключ скопирован целиком, без пробелов по краям;
• ключ не отозван в Настройки → API и MCP;
• не истёк срок, если вы его задавали;
• проект жив и подписка активна.

Отзыв

Отозвать ключ можно в любой момент в кабинете. Отзыв мгновенный. Отозванный ключ остаётся в списке серым — так в диалогах сохраняется подпись «API · имя ключа» у сообщений, которые он когда-то отправил.

Подпись действий

Всё, что делает ключ, подписано его именем. Сообщение, отправленное через API, видно оператору как «API · Синхронизация с CRM», а не как сообщение живого сотрудника. Поэтому называйте ключи понятно: имя увидят люди в диалогах.