# Scopes и полномочия Source: Locale: ru releaseGitSha: c9a428d902de0b479a981e43774f38b9ec077ed7 sourceContentDigest: 84abd238f8d3f4ad765615af44dfe46d32320ca6e2979f0a91d4d6a8eb33ac62 Version: 1 Scope определяет возможность вызвать конкретную операцию, а согласие объединяет scopes в понятные группы. Для успешного исполнения нужны выданные scopes, текущие полномочия субъекта, доступ к бизнесу и готовность операции. Прочитанная schema не расширяет ни одно из этих условий. ## Девять групп согласия OAuth consent использует девять bundles. Они раскрываются в capability scopes с удалением повторов: одинаковый scope может входить в несколько групп. Для authorization-code flow выдаются scopes принятых bundles; самостоятельный device flow показывает все девять и выдаёт scopes принятого полного согласия. | Bundle | Что человек разрешает | Consent risk | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------ | | `workspace-read` | Смотреть настройки, каталог, контент, права доступа клиентов, KB, маркетинг и рабочие данные; переписка согласуется отдельно | `read` | | `customer-conversations-read` | Читать всю переписку клиентов, включая присланные ими личные данные; без ответа | `read` | | `bot-setup` | Подключать бота и супергруппы, менять общие и юридические настройки | `write` | | `conversations` | Читать и отвечать в диалогах, отправлять уведомления, вести статусы/быстрые ответы, формы и экспорт данных клиентов | `write` | | `storefront-and-marketing` | Менять каталог, контент, витрину, домен, маркетинг, события и записи; создавать/связывать заказы | `write` | | `ai-and-knowledge` | Настраивать AI-сотрудников и наполнять базу знаний | `write` | | `access-and-integrations` | Вести команду, интеграции, сессии подключения, запросы ключей и секреты сайта | `write` | | `platform-support` | Читать обращения и отправлять новые обращения с техническими данными в TelegaFirst | `write` | | `money-operations` | Читать чувствительные платёжные сведения, выполнять денежно значимые операции, менять настройки платежей и запускать расходующие баланс рассылки | `money` | Consent risk относится к группе полномочий. У конкретного инструмента есть собственный risk `read`, `write`, `destructive` или `money`. Write-согласие может включать удаление; read-согласие не разрешает мутации. Money-согласие содержит и чувствительные чтения, поэтому чтение `payments` само по себе не становится изменением денег. ## Точные двенадцать data-plane additions Существующие 51 control-plane scope и следующие 12 scopes образуют mintable universe из 63. Добавления включены в существующие группы; десятого bundle нет. Этот набор не обещает, что credential любого типа получает все 63 scopes. | Capability scope | Bundle additions | Consent classification и действие | | ----------------------- | -------------------------------------------- | --------------------------------------------------------------------- | | `sessions` | `access-and-integrations` | `write`: создание сессий и обмен подтверждений | | `orders` | `storefront-and-marketing` | `write`: создание, связывание, обновление; не заменяет `orders:write` | | `payments` | `money-operations` | `read`: финансовые строки; раскрываются в отдельном money-согласии | | `catalog:read` | `workspace-read`, `storefront-and-marketing` | `read`: каталог | | `catalog:write` | `storefront-and-marketing` | `write`: изменение каталога, включая destructive возможности | | `entitlements` | `workspace-read`, `storefront-and-marketing` | `read`: права доступа клиентов | | `push` | `conversations` | `write`: уведомления клиентам | | `export` | `conversations` | `write`: создание заданий экспорта данных клиентов | | `content:read` | `workspace-read`, `storefront-and-marketing` | `read`: контент | | `content:write` | `storefront-and-marketing` | `write`: изменение контента | | `pull:form_submissions` | `conversations` | **`write`**: чтение и запуск нормализованного экспорта ответов форм | | `push:form_submissions` | `conversations` | `write`: создание ответов форм и отметка обработки | Нельзя выводить risk только по словам `pull` или отсутствию суффикса. Из scopes без `:read` лишь явно известные pure reads `payments` и `entitlements` классифицированы как read. Неизвестный scope не считается read. Overrides повышают risk и не понижают его. `orders:write`, `broadcasts:write`, `payments:config`, `partner:payout` и `pricing:write` сохраняют отдельный money risk. `credentials:read` имеет write risk: проверка approval может однократно доставить секрет. Просмотр имён секретов сайта не возвращает сохранённые значения. ## ALL scopes и OR authentication В REST все объявленные runtime `requiredScopes` обязательны одновременно — **ALL**. Несколько scopes в одной операции не означают «любой один». Например, если operation требует scopes A и B, caller с одним A получает отказ. Фактические требования каждой операции приведены в её reference. OpenAPI `authAlternatives` описывает альтернативные варианты аутентификации — **OR** между записями. Внутри одной записи все named security requirements и их scopes выполняются вместе — **ALL**. OR не разрешает смешать половину требований одного варианта с половиной другого и не отменяет runtime scopes, guard субъекта или tenant check. Для MCP `_meta.scope` задаёт scope целевого инструмента. Покрытие принимает точное совпадение либо явно выданные umbrellas `family:*`/`*`; это правило сравнения, а не обещание выдачи wildcard через consent. Bare family не покрывает его leaf: `payments` не разрешает `payments:config`, а `orders` не разрешает `orders:write`. REST comparator требует объявленные literal scopes; не переносите MCP umbrella-правило на произвольный REST endpoint. При `INSUFFICIENT_SCOPE` сравните требуемые scopes с выданными и эффективными, проверьте текущие права, план и платное окно. Сам код не доказывает причину отсутствия effective scope. Меняйте согласие или permissions только после установления причины; новый ключ, повторное согласие или замена credential не открывают закрытое платное окно. [Авторизация](https://telegafirst.com/docs/authorization), [INSUFFICIENT\_SCOPE](https://telegafirst.com/docs/errors#INSUFFICIENT_SCOPE). ## Платное окно Hub data plane доступен при двух одновременных условиях: 1. План — `ai_manager`, `ai_coach` или `enterprise`. 2. Платное окно открыто: `subscription_expires_at` находится в будущем. При `null` или `subscription_expires_at <= now` оно закрыто. `free`, `starter`, freemium trial, неизвестный план и topup не открывают Hub data plane. Тарифное ограничение применяется после разрешения credential к его эффективным scopes, включая person OAuth. Истёкшая подписка не продолжает давать доступ только потому, что grant был выдан раньше. Ограничение охватывает двенадцать additions выше и data-plane pulls `pull:users`, `pull:orders`, `pull:payments`. DX — исключение для диагностических возможностей, включая `GET /me` и discovery контракта; оно не даёт данных клиентов. Control-plane настройка остаётся доступной на каждом плане в пределах scopes, live permissions и readiness. MCP также учитывает собственную доступность conversational/paid операций; «control plane» не означает неограниченное платное потребление. Код тарифного отказа зависит от пути вызова. Прямой MCP-вызов может завершиться до tool layer с HTTP `403` и `INSUFFICIENT_SCOPE`, если тарифное ограничение убрало required scope из эффективного набора. Проверка plan при исполнении target, в том числе через meta-tool, может вернуть `PLAN_UPGRADE_REQUIRED`. Поэтому отсутствие этого кода не доказывает, что тариф разрешает операцию. Проверьте план, срок платного окна и эффективные права, затем повторно прочитайте контекст и `tools/list`. Новый ключ, повторное согласие или изменение permissions не заменяют нужный план и открытое платное окно. ## Live permissions, readiness и отзыв Для `OAuthGrant` сервер разрешает текущий активный бизнес человека. Для tenant-scoped `ExternalApp` и `M2MCredential` применяется их бизнес и credential provenance. Delegated control-plane scopes зависят от актуальных разрешений создавшего credential участника; оператор не получает owner-only полномочия из широкого consent. Data-plane операции дополнительно сохраняют свои route/domain checks. При удалении участника, снятии разрешения или отзыве credential прежнее согласие не восстанавливает доступ. Срок device authorization и lifecycle customer/surface JWT отличаются от OAuthGrant: проверяйте конкретный flow по [авторизации](https://telegafirst.com/docs/authorization), не придумывайте общую refresh-команду для MCP. После смены активного бизнеса или readiness обновите `tools/list`. До первого бизнеса доступны только `get_onboarding_state` и `claim_slug`; публикация сайта ещё не означает подключение бота. Отдельные quota, rate limit, payload/item limits, bot preconditions и денежные подтверждения действуют и при наличии scopes. Meta-tools `load_domain`/`describe_tool` раскрывают schema, а `execute_admin_read`/`execute_admin_write` повторно проверяют target scopes, risk, plan, bot и limiter. Schema не устанавливает callable tool; destructive/money target исполняется только через собственный typed tool. [Работа с MCP](https://telegafirst.com/docs/mcp-guide). Успех операции — принятый result и ожидаемое изменение в выбранном бизнесе. При отказе сохраните код и `traceId`, перечитайте контекст и выполните указанное действие; не повторяйте денежную мутацию вслепую. [Ошибки](https://telegafirst.com/docs/errors), [ETag и идемпотентность](https://telegafirst.com/docs/etag-and-idempotency).