Области, API-токены, OAuth и MCP

Все права, их описания, поддерживаемые ограничения и доступность для токенов перечислены в справочнике скоупов.

Программный доступ должен быть уже и проще отзываться, чем сеанс администратора-человека. Владелец автоматизации определяет нужный сценарий, владелец ресурса согласует охват, а владелец безопасности проверяет срок действия и хранение учётных данных. Успех означает, что интеграция выполняет назначенное действие, получает отказ вне своих областей и ротируется без остановки несвязанных систем.

Пользователи управляют API-токенами в Profile > Authorizations > API Tokens. Секрет показывается один раз. Храните его в менеджере секретов, назначайте минимальные области и отзывайте неиспользуемые токены.

Клиенты OAuth делегируют полномочия пользователя с явно заданными URI перенаправления и согласием. Удалённый MCP использует ту же модель ресурсов и областей, что REST API и Console; это не привилегированный обходной путь.

Используйте отдельные учётные данные для CI, мониторинга и интерактивных инструментов. Избегайте долговременных токенов администратора. Ограничивайте автоматизацию конкретными нодами, Routes, рабочими нагрузками, базами данных или проектами Pages, за которые она отвечает.

Обычные учётные данные API с префиксом gw_ и учётные данные OAuth не действуют в контура данных Gateway Inference. Для Inference используются отдельные пользовательские токены gwi_.

Записывайте создание, использование и отзыв токенов в аудит. При подозрении на раскрытие немедленно выполняйте ротацию и отдельно проверяйте активные сеансы.

Выберите тип учётных данных

Учётные данные	Использование
Session	Интерактивный доступ к Operations Console
API token	Прямая автоматизация от имени одного пользователя Gateway
OAuth client	Делегированная авторизация пользователя и сторонние приложения
Remote MCP OAuth	Клиенты инструментов, работающие через поверхность MCP Gateway
Inference token	Запросы к отдельной контура данных Gateway Inference

Не подменяйте один тип другим только потому, что его проще скопировать. Тип учётных данных определяет согласие, отзыв, оценку областей, назначение аудита и семейство доступных адресов API.

Создайте токен с минимальными правами

1. Определите точные операции и ресурсы, которыми управляет автоматизация.
2. Создайте отдельного пользователя или служебную идентичность, если атрибуцию нужно разделить.
3. Назначьте минимальные глобальные области и области ресурсов.
4. Создайте токен и один раз сохраните секрет.
5. Поместите его в менеджер секретов и передавайте только во время выполнения.
6. Проверьте один разрешённый и один запрещённый запрос.
7. Зафиксируйте владельца, назначение, ожидаемый срок действия и ротацию и зависимую систему.

Не встраивайте токены в URL репозитория, историю команд, снимки экрана или журналы. Замаскированное значение из UI нельзя получить повторно; при утрате создайте замену и отзовите прежний токен.

OAuth и MCP

Регистрируйте точные URI перенаправления и запрещайте URI с подстановочными шаблонами. Проверяйте запрошенные области при выдаче согласия и отделяйте клиенты разработки от клиентов рабочей среды. Инструменты удалённого MCP используют те же проверки авторизации и видимость ресурсов, что REST API и Console; обнаружение инструмента не выдаёт права на его выполнение.

Обрабатывайте ошибки авторизации раздельно:

• 401: аутентификация отсутствует, истекла или недействительна;
• 403: аутентифицированной идентичности не хватает области или права по тарифу;
• 409: текущее состояние ресурса или квота конфликтует с операцией;
• 422: запрос не прошёл валидацию.

Ротация и реагирование на инциденты

Создайте замену, обновите зависимую систему, подтвердите успешное использование и только затем отзовите прежние учётные данные. При подозрении на раскрытие сначала отзовите их, если это безопасно для работы сервиса, проверьте аудит, отдельно завершите связанные сеансы и замените каждый зависимый секрет, который мог быть раскрыт.

Проектирование областей и владение

Начинайте с операции, а не с названия роли. Перечислите точные вызовы чтения и изменения, затем ограничьте области ресурсов минимальной стабильной границей владения: Folder, нодой, Route, рабочей нагрузкой, базой данных или Pages Project. Добавляйте глобальную область только тогда, когда процесс действительно работает со всеми ресурсами этого типа. Разделяйте права просмотра, раскрытия, экспорта, Console, монтирования, секретов и жизненного цикла: обычное чтение не должно давать доступ к учётным данным или чувствительным операциям хоста.

У каждых учётных данных должны быть владелец, машинный потребитель, назначение, среда и условие удаления. Токен CI не должен одновременно использоваться в интерактивном терминале оператора. Для клиентов OAuth в рабочей и нерабочей средах нужны разные идентификаторы клиентов, URI перенаправления, секреты и записи согласия. При смене владельца замените учётные данные, а не оставляйте их в учётной записи ушедшего сотрудника.

Операционная проверка

Перед включением автоматизации в рабочей среде:

1. вызовите безопасный адрес чтения API с новыми учётными данными;
2. выполните одно ожидаемое изменение одноразового ресурса;
3. докажите, что ресурс вне области скрыт или запрещён;
4. убедитесь, что аудит указывает ожидаемого пользователя или OAuth client;
5. проверьте маскирование токенов, заголовков авторизации и параметров обратного вызова в журналах;
6. отзовите учётные данные и подтвердите, что потребитель безопасно прекращает работу;
7. установите замену и зафиксируйте проверенный порядок ротации.

Отзыв API token не завершает автоматически сеансы браузера, разрешения OAuth, токены Inference или учётные данные внешних поставщиков. Во время инцидента проверяйте каждое семейство отдельно.