1. LLM 에이전트에 범위 지정 API 키가 필요한 이유
일반 API 키는 베어러 자격 증명입니다: 그것을 가진 누구든 어디서나, 어떤 금액이든, 어떤 정책도 연결되지 않은 채 어떤 모델이든 호출할 수 있습니다. 그것은 자율 에이전트가 필요로 하는 것과 정반대입니다. OrcaRouter에서 API 키는 단순한 자격 증명이 아닙니다 — 그것은 범위 선언입니다. 각 키는 자체 제약(어떤 모델, 어떤 IP, 얼마만큼의 지출, 언제 만료되는지)을 담고 동시에 자신의 트래픽을 통제하는 guardrail과 firewall 정책을 가리킵니다. 키가 가리키는 정책을 편집하면 다음 요청에 적용되며, 재배포도 에이전트 코드 변경도 없습니다. 원칙은 **최소 권한(least agency)**입니다: 각 에이전트에게 자기 일을 할 수 있는 가장 좁은 신원만을 부여하고, 그 이상은 주지 않는 것. 하나의 키, 하나의 에이전트, 하나의 목적.2. 범위 지정 키가 담는 것
모든 키는 제한들의 묶음에 두 개의 정책 연결을 더한 것입니다. 각 필드는 자체 페이지에 문서화되어 있습니다 — 아래 스포크 링크가 깊이로 안내합니다.모델 제한
model_limits는 키를 이름이 지정된 모델 목록으로 제한합니다. 목록 밖의
호출은 게이트웨이를 떠나기 전에 거부됩니다 — 에이전트는 더 비싸거나 더
강력한 모델로 전환할 수 없습니다.IP 허용 목록
allow_ips는 키를 특정 소스 주소에 고정합니다. 다른 어디서든 제시된 유출된
키는 인증 계층에서 거부됩니다.쿼터, 상한 & 만료
credit_limit_usd는 평생 지출에 상한을 둡니다(0 = 무제한);
expired_time은 절대 만료 시각을 설정합니다(-1 = 절대 안 함).환경
environment는 키를 정리하고 로그를 필터링하기 위한 자유 형식 레이블
(prod, staging, dev)입니다.정책 바인딩
guardrail_id와 firewall_policy_id는 콘텐츠 정책과 툴 호출 정책을 키에
연결합니다. 연결이 없으면 워크스페이스 기본값으로 폴백합니다.토큰 객체
remain_quota / used_quota 및 is_firewall_gateway를 포함한, 키의
필드별 전체 레퍼런스.Bounded vs unbounded.
credit_limit_usd: 0과 expired_time: -1을 가진
키는 지출 상한이 없고 결코 만료되지 않습니다 — 편리하지만, 유출 시 최악의 피해
반경입니다. 각각이 언제 적절한지는
unlimited vs bounded를 참조하세요.3. 하나의 구체적인 최소 권한 키
저렴한 모델 하나로 지원 티켓을 요약하고 하나의 호스트에서 실행되는 예약된 에이전트는 거의 권한이 필요 없습니다. 그것을 위한 잘 범위 지정된 키:| 필드 | 값 | 이유 |
|---|---|---|
model_limits | 하나의 요약 모델 | 프런티어 모델로 격상할 수 없음 |
allow_ips | 스케줄러의 egress CIDR | 유출된 키가 다른 곳에서 무용지물 |
credit_limit_usd | 주간 상한 | 폭주 루프가 잔액을 소진할 수 없음 |
expired_time | 배포 종료 시점 | 자동 만료, 남아 있을 수 없음 |
guardrail_id | PII 마스킹 guardrail | 요청 텍스트가 검사됨 |
firewall_policy_id | 필요한 툴만 허용 목록 설정 | 예상치 못한 툴 호출 없음 |
4. 두 정책 평면 바인딩하기
두 연결은 키의 가장 강력한 필드이며, 연결된 정책이 비활성화되었을 때 서로 다르게 해석됩니다:guardrail_id — 콘텐츠 검사
guardrail_id — 콘텐츠 검사
워크스페이스 범위의, 순서가 있는 guardrail에 대해
요청과 응답 텍스트(PII, 시크릿, 프롬프트 인젝션)를 검사합니다. 해석:
명시적이고 활성화된
guardrail_id가 적용됩니다; 비활성화된 것은 끔
스위치입니다 — 워크스페이스 기본값으로 폴백하지 않습니다. 연결이 없으면
워크스페이스 기본 guardrail이 적용되고, 그렇지 않으면 아무것도 적용되지
않습니다.firewall_policy_id — 툴 호출 강제
firewall_policy_id — 툴 호출 강제
워크스페이스 범위의 firewall 정책에 대해 에이전트가
취하는 액션 — 툴 호출, MCP 디스패치, egress — 을 통제합니다. 해석은
guardrails와 다릅니다: 연결된 firewall 정책이 비활성화되면 워크스페이스
기본값으로 폴백하며, 강제를 끄지 않습니다.
is_firewall_gateway — 다른 종류의 키
is_firewall_gateway — 다른 종류의 키
게이트웨이 범위 토큰은 Firewall MCP 및 evaluate-hook 라우트
(
/api/v1/firewall/*)를 위해서만 발행되며, 추론을 위해서는 결코 발행되지
않습니다. 일반 키는 거기서 403을 받습니다. 이 플래그를 활성화하고
게이트웨이 키의 평문을 읽으려면 **Admin+**가 필요합니다.5. 키 섹션
키 관리
콘솔에서 키를 생성, 편집, 폐기합니다.
로테이션
다운타임 없이 키를 교체합니다.
만료 키
임시 에이전트와 CI 실행을 위한 단명 키.
키 마스킹
키는 표시 시 마스킹됩니다; 평문은 생성 시 한 번만 표시됩니다.
유출된 키
키가 노출되는 순간 해야 할 일.
최소 권한 체크리스트
모든 키를 동일한 강화 패스에 통과시키세요.
6. 키가 제어 스택에서 차지하는 위치
범위 지정 키는 방어의 첫 번째 레이어입니다 — 어떤 정책이 실행되기 전에 호출자가 누구이며 무엇에 도달할 수 있는지를 결정합니다. Guardrails와 Firewall이 그 다음 레이어입니다.AI 에이전트 보안
왜 에이전트 신원이 제어 스택의 기초인가.
Guardrails vs Firewall
키가 바인딩할 수 있는 두 정책 평면.
과도한 권한
최소 권한 키가 봉쇄하도록 만들어진 위협.