1. 세 가지 범위
세 가지 개념이 서로 중첩됩니다:- 워크스페이스 — 테넌트 경계. 워크스페이스의 모든 멤버가 동일한 guardrail과 firewall 정책 카탈로그를 공유합니다. 워크스페이스 경계를 넘는 것은 없습니다 — 워크스페이스 A에서 작성된 정책은 워크스페이스 B에게 보이지 않습니다.
- 정책 — 이름이 지정된, 워크스페이스 범위 규칙 세트 (guardrail 또는 firewall 정책). 정책을 편집하면 다음 요청에서 재배포 없이 그것에 연결된 모든 키에 효력이 발생합니다.
- 키 — 신원 플러스 연결. 키는 자체 제약을 담고 그것을 관리하는 정책을 가리킵니다.
2. 키가 담고 있는 것
각 API 키는 제한과 연결의 번들입니다. 키 에디터 (/console/token)에서
이것들을 설정하세요 — 키 생성 또는 편집은 Developer 역할 이상이 필요합니다.
| 필드 | 제한하는 것 | 설정하는 데 필요한 최소 역할 |
|---|---|---|
model_limits | 키를 특정 모델 목록으로 제한합니다 — 해당 목록 밖의 모든 호출은 게이트웨이를 떠나기 전에 거부됩니다. | Developer |
allow_ips | IP 허용 목록. 목록에 없는 주소에서의 요청은 auth 레이어에서 거부됩니다. 비어 있으면 모든 IP가 허용됩니다. | Developer |
credit_limit_usd | USD 지출 한도. 0은 무제한을 의미합니다. 게이트웨이는 이것을 키의 생애 지출에 대해 강제합니다. | Developer |
expired_time | 절대 만료 타임스탬프. -1은 키가 만료되지 않음을 의미합니다. | Developer |
environment | 키를 구성하고 로그를 필터링하기 위한 자유 형식 레이블 (예: prod, staging, dev). | Developer |
guardrail_id | 이 키에 특정 guardrail을 연결합니다. 이 키가 하는 모든 호출이 그 guardrail에 의해 검사됩니다. | Developer |
firewall_policy_id | 이 키에 특정 firewall 정책을 연결합니다. 이 키가 발행하는 모든 툴 호출이 그 정책에 의해 평가됩니다. | Developer |
is_firewall_gateway | 키를 gateway-scoped 토큰으로 표시합니다 — MCP 디스패치와 evaluate-hook 라우트를 호출하는 데 필요합니다. 일반 키는 그 라우트들에서 403을 받습니다. 게이트웨이 키 평문 읽기는 Admin이 필요합니다. | Admin (활성화 및 평문 읽기) |
3. 정책 해석 순서
모든 요청에 대해, OrcaRouter는 활성 guardrail과 firewall 정책을 독립적으로 해석합니다:- 키 연결 — 키에 명시적
guardrail_id(또는firewall_policy_id)가 있고 그 정책이 존재하고 활성화되어 있으면, 그것이 적용됩니다. - 워크스페이스 기본값 — 키에 연결이 없으면, 워크스페이스의 활성화된
is_defaultguardrail (또는 정책)이 적용됩니다. - 강제 없음 — 둘 다 설정되지 않으면, 요청은 콘텐츠 검사나 툴 호출 강제 없이 통과됩니다.
두 플레인은 연결된 정책이 _비활성화_될 때 다르게 동작합니다:
- 비활성화되거나 삭제된 guardrail 연결은 키가 어떤 guardrail도 없는 것을 의미합니다 — 비활성화가 오프 스위치입니다; 워크스페이스 기본값으로 폴백하지 않습니다.
- 비활성화된 firewall 연결은 워크스페이스 기본 firewall 정책으로 폴백합니다 — 따라서 firewall 연결을 비활성화하면 키가 워크스페이스 기본값으로 되돌아가고, 강제가 꺼지지 않습니다.
0/설정되지 않은) 연결은 항상 워크스페이스 기본값으로 폴백합니다;
둘 다 설정되지 않으면 강제가 없습니다.4. 최소 권한 키 — 에이전트당 하나의 키
가장 안전한 구성은 모든 호출자에 걸쳐 단일 워크스페이스 키를 공유하는 대신 각 에이전트에 자체 좁게 범위 지정된 키를 제공하는 것입니다. 하나의 모델만 호출하고 예약된 작업을 실행하는 에이전트에 대한 잘 범위 지정된 키는 다음과 같을 수 있습니다:model_limits:["openai/gpt-4o-mini"]— 에이전트가 더 비싸거나 더 유능한 모델로 전환할 수 없습니다.allow_ips: 스케줄러의 egress CIDR — 다른 소스는 이 키를 제시할 수 없습니다.credit_limit_usd: 주간 예산 한도 — 폭주 루프가 워크스페이스 잔액을 소진할 수 없습니다.expired_time: 스프린트 또는 배포 수명 주기의 끝 — 키가 자동으로 만료되고 재사용될 수 없습니다.guardrail_id: 이 에이전트의 데이터 민감도에 특화된 guardrail — 워크스페이스 기본값보다 엄격.firewall_policy_id: 이 에이전트가 합법적으로 필요한 툴만 허용 목록에 있는 정책.
gateway-scoped 키 (
is_firewall_gateway)는 MCP 디스패치 또는 evaluate-hook
표면에만 생성하세요 — 일반 추론 트래픽에는 절대 사용하지 마세요. 추론
경로의 게이트웨이 키는 호출자에게 /api/v1/firewall/* 라우트에 대한 접근을
제공하며, 이는 필요한 것보다 더 넓은 기능입니다. 하나의 키, 하나의 목적.5. 정책이 작성되는 곳
Guardrails와 firewall 정책은 모두 워크스페이스 범위이고 모든 멤버에게 공유되지만, 변경은 올바른 역할을 요구합니다:- 읽기 모든 guardrail, 정책, 또는 키 — 모든 워크스페이스 멤버.
- 생성 또는 변경 guardrails, firewall 정책, MCP 서버, 자율성 수준, 승인 액션, 일반 API 키 — Developer+.
is_firewall_gateway활성화 키에서; 게이트웨이 키 평문 읽기 — Admin+.
6. 다음 단계
에이전트 보안 기준선
권장 시작 자세 — 자율성 수준 스위치 하나, 그 다음 실제 트래픽에서
조정.
API 키 받기
첫 번째 키를 생성하고 콘솔에서 guardrail 또는 firewall 정책을 연결합니다.