AI 게이트웨이 가상 키(Virtual Key)

가상 키(Virtual Key)는 AI 게이트웨이가 발급하는, 게이트웨이 프록시 엔드포인트에 접근하기 위한 자격 증명입니다. 가상 키를 애플리케이션과 AI 도구에 배포하고, 실제 공급자 API 키는 게이트웨이 측에만 보관합니다. 이렇게 하면 실제 키가 여기저기 흩어지는 것을 방지할 수 있을 뿐만 아니라, 각 가상 키별로 권한 제한, 속도 제한, 교체, 폐기를 개별적으로 수행할 수 있습니다. 이 문서에서는 가상 키의 전체 수명 주기 관리를 소개합니다.

가상 키를 사용하는 이유

• 실제 키 보호 — 애플리케이션과 도구는 가상 키만 접촉하므로 공급자의 실제 키가 외부로 유출되지 않습니다.
• 용도별 권한 세분화 — 프로젝트/도구별로 서로 다른 가상 키를 생성하여 각각 사용 가능한 모델, 채널, 속도를 제한할 수 있습니다.
• 언제든 회수 가능 — 특정 키가 유출되거나 더 이상 사용되지 않을 때 해당 키만 폐기하거나 교체하면 다른 키에 영향을 주지 않습니다.

사전 요구 사항

• ServBay 계정에 로그인되어 있어야 합니다.
• 채널 페이지에서 최소 하나의 사용 가능한 채널을 추가해야 합니다.

가상 키 생성

AI 게이트웨이 → 키(Keys) 페이지로 이동하여 생성(Create) 을 클릭합니다:

• 이름 — 해당 키의 용도를 식별하는 데 사용됩니다 (예: claude-code, my-app-dev).
• 설명(선택 사항) — 추가 설명.
• 만료 시간 — 만료되지 않음 또는 특정 날짜로 설정할 수 있습니다.
• 허용된 채널(선택 사항) — 태그 다중 선택으로 해당 키가 지정된 채널로만 라우팅되도록 제한합니다. 비워두면 제한 없음.
• 허용된 모델(선택 사항) — 해당 키가 지정된 모델만 호출하도록 제한합니다. 비워두면 제한 없음.
• 속도 제한(선택 사항):
  • RPM / TPM — 분당 요청 수 / 토큰 수 상한.
  • RPD / TPD — 일일 요청 수 / 토큰 수 상한.

평문은 언제든 다시 확인 가능

키 생성이 성공하면 게이트웨이에 평문 키(예: servbay-sk-xxxxxxxx...)가 표시됩니다. 게이트웨이는 평문을 로컬에 저장하므로 이후에도 키 상세 정보에서 다시 확인할 수 있습니다. 단, 초기에 해시 방식으로 생성된 기존 키는 복구 가능한 평문이 없습니다(요청 시 409 반환). 키 유출이 의심되면 즉시 "교체"하세요.

키 목록

키 목록에는 각 가상 키의 다음 정보가 표시됩니다:

• 접두사 — 예: servbay-sk-abcd..., 식별에 사용.
• 상태 — 활성(active), 폐기됨(revoked), 만료됨(expired).
• 생성 시간 / 마지막 사용 시간.
• 권한 태그 — 허용된 모델/채널, 속도 제한.

키 관리

키 목록에서 각 키에 대해 다음 작업을 수행할 수 있습니다:

작업	설명	영향
편집(Edit)	이름, 설명, 허용된 모델/채널, 속도 제한 수정	즉시 적용, 키 자체는 변경되지 않음
교체(Renew)	평문을 재생성하며, 기존 평문은 즉시 무효화되고 새 평문은 언제든 확인 가능	해당 키를 사용하는 모든 애플리케이션과 도구를 업데이트해야 함
폐기(Revoke)	키를 즉시 비활성화하지만 감사 기록은 유지	복구 불가; 해당 키를 사용하는 요청은 거부됨
삭제(Delete)	키를 완전히 삭제	복구 불가

교체 vs 폐기

• 교체(Renew): 키 자체는 유지되지만 새 평문으로 바뀝니다. 키 유출이 의심되지만 동일한 키 구성을 계속 사용해야 하는 경우에 적합하며, 사용하는 쪽도 함께 업데이트해야 합니다.
• 폐기(Revoke): 키를 영구적으로 무효화하되 기록은 유지하여 감사에 용이합니다. 해당 키가 더 이상 필요하지 않다고 확인된 경우에 적합합니다. 교체와 폐기 모두 2차 확인이 필요합니다.

원클릭 인수와의 관계

원클릭 인수를 사용하여 특정 AI 도구를 게이트웨이로 연결하면, 게이트웨이가 해당 도구 전용 가상 키를 자동으로 생성하여 도구 설정에 기록합니다. 키 페이지에서 이렇게 자동 생성된 키를 수동으로 관리할 수도 있습니다.

자주 묻는 질문(FAQ)

• Q: 평문 키를 복사하는 것을 잊었습니다. 어떻게 해야 하나요?
  • A: 키 상세 정보에서 평문을 다시 확인할 수 있습니다. 초기에 해시 방식으로 생성된 기존 키만 확인이 불가능하며, 이 경우 "교체"를 실행하세요.
• Q: 폐기와 삭제의 차이는 무엇인가요?
  • A: 폐기는 키 기록을 유지하며(감사 목적), 삭제는 완전히 제거합니다. 둘 다 키를 즉시 무효화합니다.
• Q: "허용된 모델"을 제한한 후 애플리케이션이 다른 모델을 요청하면 어떻게 되나요?
  • A: 게이트웨이가 해당 키 권한 외의 모델 요청을 거부합니다. 애플리케이션에서 사용하는 모델이 허용 목록에 포함되어 있는지 확인하거나 제한을 해제하세요.
• Q: 속도 제한이 발동되면 어떻게 되나요?
  • A: RPM/TPM/RPD/TPD를 초과한 요청은 게이트웨이에서 제한됩니다. 통계 페이지에서 실제 사용량을 확인한 후 상한을 조정할 수 있습니다.

요약

가상 키를 사용하면 최소 권한 원칙에 따라 취소 가능한 방식으로 AI 기능을 애플리케이션과 도구에 배포할 수 있습니다. 허용된 모델/채널 제한과 속도 제한을 함께 활용하면 각 사용 사례에 맞춤형 자격 증명을 제공하고, 필요할 때 언제든 교체하거나 폐기할 수 있으며, 실제 공급자 API 키를 직접 다룰 필요가 없습니다.