메인 콘텐츠로 건너뛰기
모든 장수하는 자격 증명은 일정에 따라 교체되어야 하고, 노출의 기미가 있으면 즉시 교체되어야 합니다. API 키를 로테이션하는 자격 증명의 안전한 방법은 라이브 키를 제자리에서 변형하는 것이 결코 아닙니다 — 새것을 발행하고, 트래픽을 그쪽으로 옮긴 다음, 아무것도 의존하지 않게 되면 이전 것을 은퇴시키는 것입니다. 그 순서로 하면 작동하는 키가 없는 순간이 결코 없습니다. 이 페이지는 단계별 플레이북입니다. 더 넓은 키 생애 주기(생성 / 비활성화 / 삭제)는 키 관리를 참조하세요; 키가 담는 모든 필드는 토큰 객체를 참조하세요.
여기의 모든 콘솔 작업은 Keys 화면(/console/token)에 있으며 당신의 세션 / 액세스 토큰에서 실행됩니다 — 릴레이 키가 아닙니다. 키를 생성, 편집, 비활성화, 또는 삭제하려면 Developer 역할 이상이 필요합니다. 오직 /v1/* 추론 호출만 sk-orca-… 릴레이 키를 사용합니다.

​
1. 왜 로테이션하는가, 그리고 왜 결코 제자리에서가 아닌가

OrcaRouter의 키는 단순한 문자열이 아니라 불변의 신원입니다 — 그것은 자체 모델 허용 목록, IP 허용 목록, 지출 상한, 만료, 그리고 정책 연결을 담습니다. 기존 키의 시크릿 자재를 변경할 수 없습니다; 자격 증명과 제약은 생성 시 함께 발행됩니다. 그래서 “로테이션”은 후속 키를 발행하고 그쪽으로 마이그레이션하는 것을 의미합니다. 다음 경우에 하세요:
  • 어떤 프로덕션 자격 증명에 대해서든 고정된 주기로(분기별이 흔한 기준선);
  • 키가 유출이 의심되는 순간 — 단, 확인된 유출에는 먼저 그것을 끊고 둘째로 로테이션하세요(see 유출된 키 대응);
  • 키의 소유자(직원, 벤더 통합, 폐기된 에이전트)가 바뀔 때마다.
평문(sk-orca-…)은 생성 시 한 번 표시됩니다 — 그때 복사하세요. 이후로 콘솔은 orca-7Bf****wxyz 같은 마스킹된 형태만 보여줍니다. **Developer+**는 나중에 일반 키의 평문을 다시 공개할 수 있지만, 게이트웨이 범위 키(is_firewall_gateway)는 그 평문을 다시 읽으려면 Admin이 필요합니다 — 그러니 게이트웨이 키의 첫 공개를 당신의 유일한 신뢰할 수 있는 복사로 취급하세요.

​
2. API 키 로테이션 시퀀스

요점은 깔끔한 겹침입니다: 이전 것이 멈추기 전에 새 키가 작동합니다. 네 단계.
1

후속 키 생성

교체하는 것과 동일한 범위 — 동일한 model_limits, allow_ips, credit_limit_usd, expired_time, 그리고 동일한 guardrail_id / firewall_policy_id — 로 새 키를 발행하세요. 평문을 즉시 복사하세요. 로테이션은 범위를 조이기에도 이상적인 순간입니다: 에이전트가 더 이상 사용하지 않는 모델을 드롭하거나, IP 허용 목록을 좁히세요.
2

트래픽 마이그레이션

새 sk-orca-…를 모든 호출자에 배포하세요 — 설정, 시크릿 매니저, CI 변수, 에이전트 런타임. 어떤 시크릿 변경이든 출시하는 것과 동일한 방식으로 롤아웃하세요. 이 시점에 두 키 모두 라이브이므로, 배포를 장애 없이 시차를 두고 할 수 있습니다.
3

새 키가 부하를 운반하는지 검증

이전 것을 건드리기 전에 후속 키가 실제로 트래픽을 서비스하고 있는지 확인하세요. 새 키의 used_quota가 오르는 동안 이전 키의 것이 평평해지는 것을 지켜보세요 — 키별 사용량이 당신의 컷오버 신호입니다.
4

이전 키 은퇴

이전 키가 트래픽을 보이지 않게 되면, 먼저 비활성화(되돌릴 수 있음)하고 낙오자를 지켜본 다음, 영구히 삭제하세요. 비활성화는 일시 정지; 삭제는 돌이킬 수 없는 지점입니다.
각 키에 environment 레이블을 설정하세요 — 이전과 새 키에 걸쳐 재사용하거나, 그것을 올리세요(prod → prod-2026q2) — 그러면 겹침 창 동안 둘 다 라이브인 채로 후속 키와 선행 키가 뚜렷하게 레이블됩니다.

​
3. REST를 통한 구체적 로테이션

아래 모든 것은 콘솔 작업입니다 — 이 관리 라우트는 릴레이 키가 아니라 당신의 세션 (UserAuth) 아래에서 실행됩니다. 예약된 요약 에이전트의 키를 교체한다고 합시다. 동일한 범위로 후속 키를 생성하세요: 
# Console session token — NOT an sk-orca-… relay key
curl https://api.orcarouter.ai/api/token \
  -H "Authorization: Bearer <your-session-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "summarizer-2026q2",
    "environment": "prod",
    "model_limits_enabled": true,
    "model_limits": "openai/gpt-4o-mini",
    "credit_limit_usd": 50,
    "expired_time": -1,
    "guardrail_id": 12,
    "firewall_policy_id": 7
  }'
응답은 평문을 한 번 반환합니다("data": "sk-orca-…"). 그것을 복사하고, 요약기에 배포하고, 진행하기 전에 새 키가 서비스하고 있는지 확인하세요. 이전 키(id 481)가 트래픽을 보이지 않게 되면, 비활성화한 다음 삭제하세요: 
# Pause first (reversible) — set the old key's status to Disabled (2)
curl -X PUT https://api.orcarouter.ai/api/token \
  -H "Authorization: Bearer <your-session-token>" \
  -H "Content-Type: application/json" \
  -d '{"id": 481, "status": 2}'

# Once you're sure nothing depends on it — revoke for good
curl -X DELETE https://api.orcarouter.ai/api/token/481 \
  -H "Authorization: Bearer <your-session-token>"
키의 상태는 Enabled(1), Disabled(2), Expired(3), 또는 Exhausted(4) 중 하나입니다. 비활성화는 그것을 Disabled로 설정합니다; 그러면 키가 하는 모든 요청이 거부되며 그 구성, 연결, 이력은 그대로 유지됩니다. 삭제는 영구적입니다 — 자격 증명은 다시는 요청을 인가할 수 없으며, 삭제된 키는 복구할 수 없습니다.
이 모든 것을 API 없이 할 수 있습니다 — Keys 화면에는 New key, 키별 Disabled 토글, 그리고 Delete(단일 또는 배치)가 있습니다. 위의 REST 형태는 예약된 로테이션을 스크립팅하기 위한 것입니다.

​
4. 정책 바인딩 키와 게이트웨이 키 로테이션

키의 guardrail 및 firewall 연결은 키에 존재하므로, 후속 키는 동일한 자세를 강제하기 위해 동일한 guardrail_id와 firewall_policy_id를 담아야 합니다. 알아야 할 두 가지:
Guardrail과 firewall 정책은 워크스페이스 범위의, 이름이 지정된, 키 전체에 공유되는 리소스입니다. 키를 로테이션해도 정책 자체는 건드리지 않습니다; 당신은 그저 새 키를 기존 guardrail_id / firewall_policy_id에 다시 가리키는 것입니다. 정책은 트래픽을 중단 없이 계속 통제합니다.
is_firewall_gateway가 설정된 키는 Firewall 게이트웨이 라우트(/api/v1/firewall/*)를 구동합니다. 그것을 발행하고 그 평문을 재공개하려면 둘 다 Admin이 필요합니다. 그 시크릿을 가볍게 다시 읽을 수 없으므로, 컷오버 전에 새 게이트웨이 키의 평문을 생성 시 캡처하여 시크릿 매니저에 저장하세요.
단일 키를 — 게이트웨이든 아니든 — 여러 에이전트에 걸쳐 재사용하고 제한을 편집하여 “로테이션”하지 마세요. 에이전트당 하나의 키는 각 로테이션을 격리하고 피해 반경을 작게 유지합니다. 최소 권한 체크리스트를 참조하세요.

​
5. 긴급 로테이션 (유출 의심)

키가 노출되었다고 생각되면, 순서가 뒤집힙니다: 먼저 출혈을 멈추고, 둘째로 마이그레이션하세요.
  1. 조사하는 동안 아무것도 인가할 수 없도록 의심되는 키를 즉시 비활성화하세요 — 또는 유출이 확인되면 곧바로 삭제하세요.
  2. 후속 키를 발행하고 §2에서처럼 롤아웃하세요.
  3. 끊기 전에 유출된 키가 무엇을 했는지 검토하세요: 그 키(토큰)로 요청 로그를 필터링하여 피해 반경을 범위 지정하세요.
전체 사고 런북은 유출된 키 대응에 있습니다.
짧은 expired_time은 로테이션 보험입니다: 만료 키는 당신이 수동 로테이션을 잊더라도 스스로 은퇴하여, 어느 단일 자격 증명이 남용될 수 있는 기간에 상한을 둡니다.

​
6. 다음 단계

키 관리

이 단계들이 기반으로 삼는 생성 / 비활성화 / 폐기 생애 주기.

키에 정책 바인딩하기

동일한 guardrail과 firewall 정책을 후속 키에 담으세요.

만료 키

만료를 설정하여 키가 마감일에 스스로 로테이션하게 하세요.

유출된 키 대응

자격 증명이 노출되었을 때의 긴급 경로.
로테이션은 그저 규율 있는 겹침입니다: 선행 키가 멈추기 전에 작동하는 후속 키. 각 키를 좁게 범위 지정하면 인계가 지루하게 유지됩니다 — 그것이 바로 자격 증명 로테이션에서 당신이 원하는 것입니다.