API 키 관리

API 키 관리에서는 Orchestrator의 턴 실행 API와 구성 API에 사용할 키를 분리해 관리합니다. 외부 클라이언트가 대화를 실행하는 권한과 운영 설정을 변경하는 권한을 같은 키로 공유하지 않도록 구성합니다.

개요

Runtime API Key 저장소에는 Turn API Key와 Config API Key가 별도로 저장됩니다. 키 변경 요청에서 null은 기존 값을 유지하고 빈 문자열은 해당 키를 지우는 의미이므로 입력값을 구분해야 합니다.

키 구분

Config API Key는 운영 설정을 바꿀 수 있으므로 Turn API Key보다 좁은 관리자 범위에 배포합니다.

키 등록과 교체

1. 충분한 길이의 무작위 키를 안전한 비밀 저장소에서 생성합니다.
2. Turn과 Config 용도를 구분해 입력합니다.
3. 저장 후 전체 키가 화면이나 로그에 노출되지 않는지 확인합니다.
4. 새 키로 시험 API를 호출합니다.
5. 기존 키를 사용하는 클라이언트를 순서대로 전환합니다.
6. 전환이 끝난 뒤 이전 키를 폐기합니다.

변경 의미

키 필드에 값을 보내지 않으면 기존 값이 유지됩니다. 빈 값을 명시적으로 저장하면 인증 키가 제거됩니다. 운영에서 키를 지우면 해당 API가 의도치 않게 열리거나 모든 호출이 거부될 수 있으므로 현재 인증 정책을 먼저 확인하십시오.

사용 규칙

• 키를 소스코드, 문서, 채팅과 이슈에 적지 않습니다.
• 브라우저 로컬 저장소보다 서버 측 비밀 저장소를 사용합니다.
• Turn 키를 Config API 호출에 재사용하지 않습니다.
• 로그에는 키 원문 대신 요청 ID와 인증 결과만 남깁니다.
• 유출이 의심되면 즉시 새 키를 발급하고 이전 키를 폐기합니다.

오류 처리

401이 발생하면 호출 헤더, 키 종류와 현재 저장 상태를 확인합니다. Config API만 실패하면 Turn 키를 잘못 사용하지 않았는지 확인합니다. 키 교체 직후 일부 인스턴스만 실패하면 런타임 구성 갱신과 다중 인스턴스의 저장소 연결을 점검합니다.

감사 확인

키를 변경한 사용자, 변경 시각과 대상 종류를 감사 이력에 남깁니다. 원문 키는 감사 데이터에 저장하지 않습니다. 정기적으로 사용하지 않는 키와 오래된 클라이언트를 정리합니다.