Для AI-агентов: markdown этой страницы — /docs/scopes-and-permissions.mdиндекс документации — /llms.txt
Scopes и полномочия
Обновлено
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 не открывают закрытое платное окно. Авторизация, INSUFFICIENT_SCOPE.
Платное окно
Hub data plane доступен при двух одновременных условиях:
План —
ai_manager,ai_coachилиenterprise.Платное окно открыто:
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 по авторизации, не придумывайте общую 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.
Успех операции — принятый result и ожидаемое изменение в выбранном бизнесе. При отказе сохраните код и traceId, перечитайте контекст и выполните указанное действие; не повторяйте денежную мутацию вслепую. Ошибки, ETag и идемпотентность.