# Авторизация и отзыв доступа Source: Locale: ru releaseGitSha: c9a428d902de0b479a981e43774f38b9ec077ed7 sourceContentDigest: 32fce7131721855ef929a7f8914d870eef23fe9fd0eda0979ce622c2f111f870 Version: 1 Выберите способ входа по субъекту, который выполняет действие. Для своего AI-агента войдите как человек через OAuth. Для серверной интеграции используйте выданный ей credential и его scopes. Покупатель входит в свой кабинет отдельной сессией; такой вход не даёт прав владельца бизнеса. ## Кто действует | Субъект и credential | Область действия | Ограничение | | ------------------------------------------------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | Владелец или оператор через person OAuth (`OAuthGrant`) | Доступные этому человеку бизнесы и его текущий активный бизнес | Согласованные scopes и текущие права человека; оператор сохраняет роль оператора | | Tenant API key (`ExternalApp`) | Бизнес интеграции и разрешённые scopes | Ключ не переключает общий активный указатель человека и не создаёт owner-полномочия | | Headless/CI credential (`M2MCredential`) | Бизнес credential и выданные scopes | Реальный отдельный вид credential с проверкой статуса, отзыва и разрешений | | Surface-session JWT | Контекст конкретной аутентифицированной поверхности | JWT сам по себе не доказывает право управлять бизнесом; требуется предусмотренная этой поверхностью проверка субъекта | | Customer session | Собственные заказы, билеты и записи покупателя | Проверка tenant и принадлежности объекта покупателю; право оператора из неё не выводится | `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` по [инструкции клиента](https://telegafirst.com/docs/mcp-guide). При 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`; продолжите [первую настройку](https://telegafirst.com/docs/getting-started#new-business). 5. Для существующего бизнеса проверьте активный slug. При доступном `list_accessible_bots` выберите бизнес из фактического списка; при необходимости используйте разрешённый `switch_active_bot` и повторно обновите `tools/list`. Person OAuth разрешает активный бизнес через текущий выбор человека. Этот выбор общий для его подключений и чата платформенного бота. Вход оператора не делает его владельцем; наличие business в прежнем списке не доказывает, что доступ сохранился сегодня. Успех подключения — действующий credential, ожидаемый активный бизнес и инструменты, соответствующие согласованным правам и readiness. Подтверждение входа не является подтверждением каждой денежной операции: её собственные scopes, подготовка, execution и необходимые owner-подтверждения сохраняются. [Права и ограничения](https://telegafirst.com/docs/scopes-and-permissions). ## Независимый device grant Для диагностики без AI-клиента используйте [curl device grant](https://telegafirst.com/docs/curl-device-grant). Он регистрирует собственный public diagnostic client и получает собственную Telegram-ссылку. Не извлекайте токен или client identity из ChatGPT, Claude, Codex либо другого подключения. Device flow запрашивает все девять существующих consent bundles. Перед подтверждением человеку показывают их права, включая customer data, формы, экспорт, записи каталога и финансовые сведения. Сервер связывает выданные scopes с показанным и принятым согласием. Отсутствующее, изменившееся, просроченное или отклонённое согласие не выдаёт grant. Обезличенный контрактный ответ после успешного подтверждения и обмена; `` — заглушка секрета, не готовый токен: ```json {"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-матрица](https://telegafirst.com/docs/scopes-and-permissions). ## Отзыв и ошибки входа Владелец управляет выданными доступами в [настройках бизнеса](https://telegafirst.com/docs/business-settings). Когда 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 требует существующего процесса согласования, а не ручного расширения данных токена. | Отказ | Что проверить | | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | HTTP 401 | Отсутствующий, неверный или отозванный credential и правильный endpoint; [INVALID\_API\_KEY](https://telegafirst.com/docs/errors#INVALID_API_KEY), [INVALID\_JWT](https://telegafirst.com/docs/errors#INVALID_JWT) | | `INSUFFICIENT_SCOPE` | Нужные scopes операции, выданный и эффективный наборы, текущие permissions, план и платное окно; код не устанавливает точную причину отказа. [Ошибка](https://telegafirst.com/docs/errors#INSUFFICIENT_SCOPE) | | `PLAN_UPGRADE_REQUIRED` | Поддерживаемый план и открытое платное окно; [описание](https://telegafirst.com/docs/scopes-and-permissions#paid-window) | | Device `authorization_pending` | Человек ещё не подтвердил; продолжайте polling с разрешённым interval | | Device `slow_down` | Увеличьте polling interval на пять секунд | | Device `access_denied` / `expired_token` | Прекратите polling; для нового входа создайте новое authorization | Для поддержки передайте код ошибки и `traceId`, если сервер его вернул, без credentials и личных данных. [Справочник ошибок](https://telegafirst.com/docs/errors). При тарифном ограничении прямой MCP-вызов может вернуть HTTP `403` с `INSUFFICIENT_SCOPE` до исполнения инструмента; runtime-проверка plan целевого инструмента может сообщить `PLAN_UPGRADE_REQUIRED`. Не используйте отсутствие второго кода как доказательство доступности тарифа. Повторное согласие, новый ключ, изменение permissions или замена credential не заменяют нужный план и открытое платное окно.