Перейти к основному содержанию
Чтобы прогонять вызовы инструментов через agent firewall извне ретрансляции модели — ваш собственный цикл агента, вызывающий хук evaluate, или MCP-клиент, подключающийся к MCP-шлюзу — вы аутентифицируетесь выделенным ключом с областью firewall-gateway, а не обычным ретрансляционным ключом sk-orca-…. Обычный ключ получает 403 на токен-аутентифицированных маршрутах шлюза firewall (колбэк подтверждения — единственное исключение: он подписан HMAC, не ограничен токеном). Эта страница покрывает, что такое API-ключ шлюза firewall, как создать один и почему область ограничена Admin+. О самом движке см. обзор Firewall и глубокий справочник на Firewall.

​
1. Что такое API-ключ шлюза firewall

Каждый токен (API-ключ) в вашем рабочем пространстве несёт флаг is_firewall_gateway. Когда он true, ключу разрешено достигать поверхность шлюза firewall:
МаршрутЧто он делает
POST /api/v1/firewall/evaluatePre-dispatch вердикт для одного вызова инструмента.
POST /api/v1/firewall/evaluate_planPre-execution проверка многошагового плана.
ANY /api/v1/firewall/mcpЕдиный эндпоинт MCP-шлюза.
GET /api/v1/firewall/mcp_serversПеречислить зарегистрированные MCP-серверы рабочего пространства (возвращает расшифрованную upstream-аутентификацию).
GET /api/v1/firewall/approvals/:idОпросить состояние подтверждения удержанного вызова.
Ключ с is_firewall_gateway = false (по умолчанию) — это обычный ретрансляционный ключ — он обслуживает трафик модели /v1/* и, если вы привязали политику через firewall_policy_id, его вызовы инструментов управляются inline. Но он не может вызывать маршруты шлюза выше.
Два разных ключа, две разные работы. Ваш ретрансляционный ключ (с привязанным firewall_policy_id) — то, чем ваш агент говорит с моделями — firewall управляет его вызовами инструментов автоматически. Ключ шлюза firewall — то, чем рантайм вашего агента просит firewall вердикт напрямую или проксирует MCP tools/call через шлюз. Большинству рабочих пространств ключ шлюза нужен только когда они принимают хук evaluate или MCP-шлюз.

​
2. Почему обычный ключ получает 403

Область шлюза разблокирует две чувствительные к секретам возможности, так что она намеренно отгорожена от обычных ключей:
  • /evaluate принимает поданный вызывающим request_id, который втекает в событие firewall и записи подтверждений. Если бы любой ключ модели мог подделать события аудита или молча зондировать исходы политики, это подорвало бы след.
  • /mcp_servers возвращает расшифрованные upstream-учётные данные, так что прокси SDK может диспетчеризовать к вашим зарегистрированным MCP-серверам. Это чтение учётных данных, не вызов модели.
Из-за этого обработчик проверяет флаг is_firewall_gateway предъявленного токена и возвращает HTTP 403, когда он отсутствует: 
{
  "success": false,
  "message": "token lacks firewall_gateway scope — mint a dedicated gateway token"
}
Не переиспользуйте высоконагруженный ретрансляционный ключ как ключ шлюза и не переиспользуйте ключ шлюза для ретрансляционного трафика. Держите ключ плоскости действий отдельно, так чтобы его радиус поражения и ротация были независимы от ваших ключей модели.

​
3. Создание — ограничено ролью Admin+

Установка is_firewall_gateway = true требует Admin рабочего пространства или выше. Developer может создавать и редактировать обычные ключи, но не может создать ключ с областью шлюза — флаг — это забота управления секретами, так что он сидит выше обычной роли записи токенов. Вы настраиваете ключи в консоли, под API-ключами вашего рабочего пространства. Чтобы создать ключ шлюза:
1

Откройте API-ключи как Admin

Войдите как Admin рабочего пространства (или выше) и откройте страницу API-ключей в консоли.
2

Создайте ключ с областью шлюза

Создайте новый ключ и включите его область firewall gateway (is_firewall_gateway). Сессия с ролью Developer не увидит, как область вступает в силу — сервер держит флаг false для не-админов.
3

Скопируйте ключ один раз

Скопируйте полное значение ключа при создании. После этого консоль маскирует его при отображении, а чтение plaintext ключа шлюза само по себе Admin+ — не-админы получают строки шлюза опущенными из ответа «fetch my keys».
Понижение флага более разрешительно, чем повышение: очистка is_firewall_gateway (понижение ключа шлюза обратно до обычного ключа) открыта любой роли, которая может редактировать ключ. Только повышение его до true — Admin+.

​
Шлюзы ролей с одного взгляда

ДействиеРоль
Создать/редактировать обычный ключDeveloper+
Установить is_firewall_gateway = trueAdmin+
Прочитать plaintext ключа шлюза обратноAdmin+
Очистить is_firewall_gateway (понизить)любой редактор ключей

​
4. Один конкретный пример

Вы запускаете цикл агента и хотите проверить вызов инструмента до его диспетча. Как Admin, создайте ключ шлюза в консоли, затем вызовите хук evaluate из вашего рантайма с этим ключом: 
curl https://api.orcarouter.ai/api/v1/firewall/evaluate \
  -H "Authorization: Bearer sk-orca-GATEWAY-KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "shell.exec",
    "arguments": { "command": "rm -rf /" },
    "request_id": "run-42-step-3"
  }'
Firewall разрешает активную политику вашего рабочего пространства и возвращает вердикт — allow, audit, deny, sanitize, pending_approval или разрешение cap_cost. Ваш агент действует по нему: диспетч при allow, пропуск при deny, опрос id подтверждения при pending_approval. Тот же ключ шлюза аутентифицирует маршруты опроса подтверждений и MCP.
Направляете MCP-клиент (Claude Desktop, Cursor, фреймворк агента) на https://api.orcarouter.ai/api/v1/firewall/mcp? Используйте ключ шлюза как его bearer-токен. Каждый tools/call тогда вычисляется на поверхности mcp surface до того, как пересылается upstream.

​
5. Куда он вписывается

Ключ шлюза аутентифицирует маршруты шлюза. Он не заменяет консольную сессию, которой вы создаёте политику: создание политик, редактирование правил, регистрация MCP-серверов и разрешение подтверждений — всё выполняется под вашей собственной сессией на /api/workspace/firewall/* (чтения настроек, политики и обнаруженных инструментов открыты каждому участнику; песочница теста вхолостую и все записи требуют Developer+). Ключ шлюза несёт только запросы вердиктов и MCP-диспетч из вашего machine-to-machine рантайма.

Область: ключи, политики, рабочие пространства

Как firewall_policy_id ключа и область шлюза связаны с границей рабочего пространства.

Подтверждения

Поток удержанного вызова, который ваш ключ шлюза опрашивает и повторно отправляет.

Вебхук подтверждений

Подписанный HMAC колбэк, который разрешает удержанный вызов вне основного канала.

MCP-серверы

Регистрируйте и управляйте MCP-серверами за эндпоинтом шлюза.

​
6. FAQ

Повышение is_firewall_gateway до true — Admin+. Запись с ролью Developer, которая устанавливает флаг, молча держится на false (так что несвязанное переименование или правка квоты в том же запросе всё равно проходит) — ключ просто не понесёт область. Пересоздайте или отредактируйте его как Admin.
Предъявленный ключ не имеет области шлюза. Подтвердите, что он был создан с is_firewall_gateway = true Admin’ом — обычный ретрансляционный ключ всегда получает 403 на этих маршрутах. См. §2.
Технически ключ с областью шлюза может также обслуживать ретрансляционный трафик /v1/*, но держите их раздельно: один ретрансляционный ключ (с привязанным firewall_policy_id) для моделей, один ключ шлюза для маршрутов evaluate/MCP/подтверждений. Независимая ротация, меньший радиус поражения.
Ключи маскируются после создания, а чтение plaintext ключа шлюза — Admin+. Если вы не скопировали его при создании, создайте новый ключ шлюза и выведите старый из эксплуатации.