메인 콘텐츠로 건너뛰기
모델 릴레이 밖에서 에이전트 firewall을 통해 툴 호출을 실행하려면 — 자체 에이전트 루프가 evaluate 훅을 호출하거나, MCP 클라이언트가 MCP 게이트웨이에 연결 — 일반 sk-orca-… 릴레이 키가 아니라 전용 firewall-gateway-scoped 키로 인증합니다. 일반 키는 토큰 인증 firewall 게이트웨이 라우트에서 403을 받습니다(승인 콜백이 한 예외 — 그것은 토큰 게이트가 아니라 HMAC 서명됨). 이 페이지는 firewall 게이트웨이 API 키가 무엇인지, 하나를 어떻게 발행하는지, 그리고 왜 범위가 Admin+로 게이트되는지를 다룹니다. 엔진 자체는 Firewall 개요와 Firewall의 심층 레퍼런스를 참조하세요.

​
1. firewall 게이트웨이 API 키란

워크스페이스의 모든 토큰(API 키)은 is_firewall_gateway 플래그를 지닙니다. 그것이 true일 때, 키는 firewall 게이트웨이 표면에 도달할 수 있습니다:
라우트무엇을 하는가
POST /api/v1/firewall/evaluate한 툴 호출에 대한 디스패치 전 판정.
POST /api/v1/firewall/evaluate_plan다단계 계획에 대한 실행 전 검사.
ANY /api/v1/firewall/mcp통합 MCP 게이트웨이 엔드포인트.
GET /api/v1/firewall/mcp_servers워크스페이스의 등록된 MCP 서버 열거(복호화된 업스트림 auth 반환).
GET /api/v1/firewall/approvals/:id보류된 호출의 승인 상태 폴링.
is_firewall_gateway = false(기본값)인 키는 일반 릴레이 키입니다 — /v1/* 모델 트래픽을 서비스하고, firewall_policy_id를 통해 정책을 연결했다면 그 툴 호출이 인라인으로 통제됩니다. 하지만 위의 게이트웨이 라우트를 호출할 수는 없습니다.
서로 다른 두 키, 서로 다른 두 일. 당신의 릴레이 키 (firewall_policy_id 연결됨)는 에이전트가 모델과 대화하는 데 사용하는 것입니다 — firewall이 그 툴 호출을 자동으로 통제합니다. firewall 게이트웨이 키는 에이전트 런타임이 firewall에게 판정을 직접 요청하거나, MCP tools/call을 게이트웨이를 통해 프록시하는 데 사용하는 것입니다. 대부분의 워크스페이스는 evaluate 훅이나 MCP 게이트웨이를 채택한 후에야 게이트웨이 키가 필요합니다.

​
2. 일반 키가 403을 받는 이유

게이트웨이 범위는 두 가지 시크릿 민감 기능을 잠금 해제하므로, 의도적으로 일반 키로부터 벽으로 막혀 있습니다:
  • /evaluate는 호출자가 공급한 request_id를 받습니다. 그것은 firewall 이벤트와 승인 레코드로 흐릅니다. 어떤 모델 키든 감사 이벤트를 위조하거나 정책 결과를 조용히 탐색할 수 있다면 추적을 약화시킬 것입니다.
  • /mcp_servers는 복호화된 업스트림 자격 증명을 반환합니다. 그래서 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

Admin으로 API 키 열기

워크스페이스 Admin(또는 그 이상)으로 로그인하고 콘솔의 API 키 페이지를 엽니다.
2

게이트웨이 범위로 키 생성

새 키를 생성하고 그 firewall 게이트웨이 범위 (is_firewall_gateway)를 활성화합니다. Developer 역할 세션은 범위가 적용되는 것을 보지 못합니다 — 서버는 비-admin에 대해 플래그를 false로 유지합니다.
3

키를 한 번 복사

생성 시 전체 키 값을 복사하세요. 그 후 콘솔은 표시 시 그것을 마스킹하고, 게이트웨이 키의 평문을 다시 읽는 것 자체가 **Admin+**입니다 — 비-admin은 “fetch my keys” 응답에서 게이트웨이 행이 생략됩니다.
플래그를 낮추는 것은 올리는 것보다 더 허용적입니다: is_firewall_gateway를 지우는 것(게이트웨이 키를 일반 키로 강등)은 키를 편집할 수 있는 모든 역할에게 개방됩니다. 그것을 true로 올리는 것만 Admin+입니다.

​
역할 게이트 한눈에 보기

액션역할
일반 키 생성/편집Developer+
is_firewall_gateway = true 설정Admin+
게이트웨이 키의 평문 다시 읽기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에서 건너뛰기, pending_approval에서 승인 id 폴링. 같은 게이트웨이 키가 승인 폴과 MCP 라우트를 인증합니다.
MCP 클라이언트(Claude Desktop, Cursor, 에이전트 프레임워크)를 https://api.orcarouter.ai/api/v1/firewall/mcp로 가리키나요? 게이트웨이 키를 그 bearer 토큰으로 사용하세요. 그러면 모든 tools/call이 업스트림으로 전달되기 전에 mcp 표면에서 평가됩니다.

​
5. 이것이 어디에 들어맞는가

게이트웨이 키는 게이트웨이 라우트를 인증합니다. 정책을 작성하는 데 사용하는 콘솔 세션을 대체하지 않습니다: 정책 생성, 규칙 편집, MCP 서버 등록, 그리고 승인 해결은 모두 /api/workspace/firewall/*에서 자체 세션하에 실행됩니다(설정, 정책, discovered-tool 읽기는 모든 멤버에게 개방; dry-run 테스트 샌드박스와 모든 쓰기는 Developer+ 요구). 게이트웨이 키는 머신-투-머신 런타임에서 판정 요청과 MCP 디스패치만 담습니다.

범위: 키, 정책, 워크스페이스

키의 firewall_policy_id와 게이트웨이 범위가 워크스페이스 경계와 어떻게 관계되는가.

Approvals

게이트웨이 키가 폴링하고 재제출하는 보류 호출 흐름.

승인 웹훅

보류된 호출을 대역 외에서 해결하는 HMAC 서명 콜백.

MCP 서버

게이트웨이 엔드포인트 뒤에서 MCP 서버를 등록하고 통제합니다.

​
6. FAQ

is_firewall_gateway를 true로 올리는 것은 **Admin+**입니다. 플래그를 설정하는 Developer 역할 쓰기는 조용히 false로 유지됩니다(그래서 같은 요청의 무관한 이름 변경이나 쿼터 편집은 여전히 성공) — 키가 그저 범위를 담지 않을 뿐입니다. Admin으로 다시 생성하거나 편집하세요.
제시된 키가 게이트웨이 범위가 아닙니다. Admin이 is_firewall_gateway = true로 발행했는지 확인하세요 — 일반 릴레이 키는 이 라우트들에서 항상 403을 받습니다. §2 참조.
기술적으로 게이트웨이 범위 키는 /v1/* 릴레이 트래픽도 서비스할 수 있지만, 분리해 유지하세요: 모델용 릴레이 키 하나(firewall_policy_id 연결됨), evaluate/MCP/승인 라우트용 게이트웨이 키 하나. 독립적 회전, 더 작은 폭발 반경.
키는 생성 후 마스킹되며, 게이트웨이 키의 평문을 읽는 것은 Admin+입니다. 발행 시점에 복사하지 않았다면, 새 게이트웨이 키를 생성하고 이전 것을 폐기하세요.