Для AI-агентов: markdown этой страницы — /docs/authorization.md · индекс документации — /llms.txt

Авторизация и отзыв доступа

Обновлено 2 октября 2026 г.

Выберите способ входа по субъекту, который выполняет действие. Для своего AI-агента войдите как человек через OAuth. Для серверной интеграции используйте выданный ей credential и его scopes. Покупатель входит в свой кабинет отдельной сессией; такой вход не даёт прав владельца бизнеса.

#Кто действует

OAuthGrant, ExternalApp и M2MCredential — реальные виды credential. Способ аутентификации не должен превращать человека в другого актора или давать дополнительные scopes. Сервер применяет одинаковые требования конкретной операции после разрешения credential. API key не является способом обойти отказ OAuth, тариф, readiness или live permissions.

create_session, get_session_status и exchange_session_approval_code относятся к сессиям входа/связывания внешней поверхности. Они не заменяют person OAuth подключения AI-клиента. Полученный surface/customer JWT нельзя использовать как доказательство полномочий владельца. Для buyer-объекта требуется customer guard; для управления tenant — собственная проверка доступного бизнеса и прав.

#Подключение AI-агента человеком

1. Добавьте https://mcp.telegafirst.com/api/v1/mcp по инструкции клиента. При HTTP 401 клиент читает WWW-Authenticate и начинает OAuth.

2. Прочитайте показанное согласие. Bundles объединяют понятные человеку группы операций, затем сервер раскрывает их в capability scopes. Само имя bundle не является отдельным полномочием.

3. Подтвердите доступ в Telegram от своего имени. Отказ не выпускает credential. В authorization-code flow клиент использует привязку к своему redirect URI, resource MCP и PKCE; произвольный код от другого клиента не подходит.

4. Обновите tools/list и проверьте get_onboarding_state. Для нового бизнеса доступны только get_onboarding_state и claim_slug; продолжите первую настройку.

5. Для существующего бизнеса проверьте активный slug. При доступном list_accessible_bots выберите бизнес из фактического списка; при необходимости используйте разрешённый switch_active_bot и повторно обновите tools/list.

Person OAuth разрешает активный бизнес через текущий выбор человека. Этот выбор общий для его подключений и чата платформенного бота. Вход оператора не делает его владельцем; наличие business в прежнем списке не доказывает, что доступ сохранился сегодня.

Успех подключения — действующий credential, ожидаемый активный бизнес и инструменты, соответствующие согласованным правам и readiness. Подтверждение входа не является подтверждением каждой денежной операции: её собственные scopes, подготовка, execution и необходимые owner-подтверждения сохраняются. Права и ограничения.

#Независимый device grant

Для диагностики без AI-клиента используйте curl device grant. Он регистрирует собственный public diagnostic client и получает собственную Telegram-ссылку. Не извлекайте токен или client identity из ChatGPT, Claude, Codex либо другого подключения.

Device flow запрашивает все девять существующих consent bundles. Перед подтверждением человеку показывают их права, включая customer data, формы, экспорт, записи каталога и финансовые сведения. Сервер связывает выданные scopes с показанным и принятым согласием. Отсутствующее, изменившееся, просроченное или отклонённое согласие не выдаёт grant.

Обезличенный контрактный ответ после успешного подтверждения и обмена; <ACCESS_TOKEN> — заглушка секрета, не готовый токен:

{"access_token":"<ACCESS_TOKEN>","token_type":"Bearer","scope":"workspace-read customer-conversations-read bot-setup conversations storefront-and-marketing ai-and-knowledge access-and-integrations platform-support money-operations"}

Поле scope этого OAuth-ответа перечисляет bundles. В сохранённом grant находятся их раскрытые capability scopes; прямое сравнение этого поля с _meta.scope инструмента будет неправильным. В этом ответе нет expires_in и refresh_token; не переносите сюда lifecycle surface-session JWT. Device authorization code при этом имеет собственный короткий срок и polling interval, которые нужно соблюдать по ответу сервера.

Этот пример описывает форму ответа самостоятельного device-клиента и не подтверждает ручной вход в конкретном AI-хосте. Храните полученный секрет локально приватно; не вставляйте его в промпт, публичную переписку или отчёт диагностики.

#Текущие права и платное окно

Согласие задаёт верхнюю границу scopes. Исполнение учитывает актуальные полномочия владельца/участника, membership, revoke, активный бизнес, readiness, тариф, quota и resource limiter. Снятое разрешение участника не восстанавливается старым согласованным credential. Документация и прочитанная schema не дают дополнительные права.

Для Hub data plane нужен ai_manager, ai_coach или enterprise и открытое платное окно. free, starter, trial и покупка topup сами по себе его не открывают. Отсутствующая или истёкшая дата платного окна закрывает data plane. Конфигурационные операции и DX остаются доступными в пределах своих прав; их доступность не разрешает читать данные клиентов. Точная scope-матрица.

#Отзыв и ошибки входа

Владелец управляет выданными доступами в настройках бизнеса. Когда owner-facing инструменты доступны, list_connections с {} возвращает подключения человека, host, последнее использование, название активного бизнеса и display token_prefix. Выберите нужное подключение и вызовите revoke_connection с token_prefix из этого списка. Нужны соответственно credentials:read и credentials:write и owner-session context; API key другого субъекта его не заменяет. Отзыв не требует второго owner-подтверждения. Если prefix неоднозначен, сервер отказывает с CONFLICT; не угадывайте target. Удаление коннектора из AI-клиента само по себе не доказывает отзыв на сервере.

После server-side revoke credential больше не аутентифицируется; старый список инструментов или сохранённая schema этого не меняют. Для восстановления доступа пройдите новый разрешённый вход. Обновление scopes требует существующего процесса согласования, а не ручного расширения данных токена.

Для поддержки передайте код ошибки и traceId, если сервер его вернул, без credentials и личных данных. Справочник ошибок.

При тарифном ограничении прямой MCP-вызов может вернуть HTTP 403 с INSUFFICIENT_SCOPE до исполнения инструмента; runtime-проверка plan целевого инструмента может сообщить PLAN_UPGRADE_REQUIRED. Не используйте отсутствие второго кода как доказательство доступности тарифа. Повторное согласие, новый ключ, изменение permissions или замена credential не заменяют нужный план и открытое платное окно.