# Scopes и полномочия Source: Locale: ru releaseGitSha: 0bb11ef116e17ec64c802d5476eaff442e53d252 sourceContentDigest: d494d24aa2e102ec8759789d5afcbf7cf0025d78c871c485ea1c3932a6d8870f Version: 2 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: пока он действует, data plane открыт любому credential бизнеса, включая ключи интеграций `ExternalApp` и `M2MCredential`. Признак триала учитывается только при отсутствии платного окна (`subscription_expires_at` равен `null`); оплаченный Starter триалом не считается. 2. **Личный OAuth-грант владельца или оператора** в его активном бизнесе, если платное окно открыто на **любом** плане, включая Starter (`starter`). Права такого агента совпадают с правами человека в CRM: data-plane scopes проходят через те же флаги участника, что и control plane, у владельца ограничений участника нет. 3. **Ключ интеграции вне триала** (`ExternalApp`, `M2MCredential`): план `ai_manager`, `ai_coach` или `enterprise` **и** открытое платное окно. Платное окно открыто, если `subscription_expires_at` находится в будущем. При `null` или `subscription_expires_at <= now` оно закрыто. Без триала и без открытого платного окна (`free`), а также при неизвестном плане и одном topup data plane закрыт для любого credential: у такого бизнеса нет CRM, и личный агент получает ровно то же. После окончания триала ключи интеграций остаются закрытыми, пока не оплачен AI Manager или выше; личный агент продолжает работу после оплаты любого тарифа. Оплата не расширяет права сверх scopes, live permissions и readiness. Истёкшая подписка не продолжает давать доступ только потому, что grant был выдан раньше. Ограничение охватывает двенадцать additions выше и data-plane pulls `pull:users`, `pull:orders`, `pull:payments`. DX — исключение для диагностических возможностей, включая `GET /me` и discovery контракта; оно не даёт данных клиентов. Control-plane настройка остаётся доступной на каждом плане в пределах scopes, live permissions и readiness; обращения в поддержку доступны на любом уровне. Инструменты, доступные только на AI Coach и Enterprise, пробный период не открывает. MCP также учитывает собственную доступность conversational/paid операций; «control plane» не означает неограниченное платное потребление. Код отказа зависит от причины и от поверхности. Различитель — может ли новое согласие устранить причину. **MCP:** scope, который не был выдан, останавливает прямой вызов до tool layer: HTTP `403`, `INSUFFICIENT_SCOPE` и `WWW-Authenticate: Bearer error="insufficient_scope"` — только такой отказ может исправить новое согласие. Scope, снятый тарифным ограничением data plane (в том числе выданный раньше), не даёт `WWW-Authenticate`: вызов доходит до инструмента и возвращается ошибка инструмента `PLAN_UPGRADE_REQUIRED` с подсказкой; снятый живыми правами участника — `FORBIDDEN`. Тот же `PLAN_UPGRADE_REQUIRED` возвращается для инструментов, доступных только на AI Coach и Enterprise, в том числе при вызове через meta-tool. **REST:** тарифное ограничение отвечает HTTP `403` `PLAN_UPGRADE_REQUIRED`, невыданный scope — `INSUFFICIENT_SCOPE`. Проверьте план, пробный период, срок платного окна и эффективные права, затем повторно прочитайте контекст и `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).