AI 게이트웨이 가상 키(Virtual Key)
가상 키(Virtual Key)는 AI 게이트웨이가 발급하는 인증 토큰으로, 게이트웨이 프록시 엔드포인트에 접근하는 데 사용됩니다. 실제 공급업체 API Key는 게이트웨이에만 보관되며, 앱과 AI 도구에는 오직 가상 키만 배포됩니다. 이를 통해 실제 키의 유출을 막고, 가상 키별로 권한, 속도, 회전 및 폐기 등 다양한 관리를 할 수 있습니다. 이 문서는 가상 키의 전체 수명 주기 관리를 안내합니다.
왜 가상 키를 사용해야 하나요?
- 실제 키 보호 — 앱과 도구는 가상 키만 사용하여, 공급업체의 실제 Key 유출 위험이 없습니다.
- 목적별 세분화 권한 부여 — 프로젝트/도구별로 서로 다른 가상 키를 생성하고, 각 키에 사용 가능한 모델, 채널, 요청 속도 등을 분리해서 설정할 수 있습니다.
- 언제든 회수 가능 — 특정 키가 유출되거나 더 이상 필요하지 않을 경우, 즉시 폐기 혹은 회전할 수 있습니다. 다른 키에는 영향이 없습니다.
사전 조건
- ServBay 계정에 로그인 되어 있어야 합니다.
- 채널 페이지에서 최소 1개 이상의 사용 가능한 채널이 추가되어 있어야 합니다.
가상 키 생성하기
AI 게이트웨이 → 키(Keys) 페이지로 이동하여 생성(Create) 버튼을 클릭합니다.
- 이름 — 키의 용도를 구분할 수 있는 명칭 예)
claude-code,my-app-dev - 설명(선택사항) — 추가 정보를 입력할 수 있습니다.
- 만료 시간 — 만료 없이 영구 사용 또는 특정 날짜 지정 가능
- 허용 채널(선택사항) — 태그를 복수 선택하여 해당 키가 지정한 채널에만 라우팅되도록 설정(미설정 시 제한 없음)
- 허용 모델(선택사항) — 해당 키로 호출 가능한 모델 제한(미설정 시 제한 없음)
- 속도 제한(선택사항):
- RPM / TPM — 분당 요청 수 / 분당 토큰 수 제한
- RPD / TPD — 일일 요청 수 / 일일 토큰 수 제한
평문 키는 한 번만 표시됩니다
키 생성이 완료되면 게이트웨이가 1회성 평문 키(예: servbay-sk-xxxxxxxx...)를 보여줍니다. 즉시 복사 및 보관하세요. 창을 닫으면 앞부분 프리픽스만 확인할 수 있고, 전체 평문 키는 다시 확인할 수 없습니다. 분실 시에는 '회전'을 통해 새 키를 발급해야 합니다.
키 목록
키 목록에서는 각 가상 키의 다음 항목을 확인할 수 있습니다.
- 프리픽스 — 예:
servbay-sk-abcd...(키 식별용) - 상태 — 활성(active), 폐기(revoked), 만료(expired)
- 생성 일시 / 마지막 사용 일시
- 권한 태그 — 허용된 모델/채널, 속도 제한
키 관리
키 목록에서 각각의 키에 대해 다음 작업을 수행할 수 있습니다.
| 작업 | 설명 | 영향 |
|---|---|---|
| 수정(Edit) | 이름, 설명, 허용 모델/채널, 속도 제한 수정 | 즉시 반영, 키 자체는 변하지 않음 |
| 회전(Renew) | 평문 키 재생성, 기존 평문 즉시 폐기, 새 평문 1회 표시 | 해당 키를 사용하는 모든 앱/도구에서 키 값 변경 필요 |
| 폐기(Revoke) | 키를 즉시 비활성화, 감사 기록은 보존 | 복구 불가, 관련 요청은 모두 거부됨 |
| 삭제(Delete) | 키 완전 삭제 | 복구 불가 |
회전과 폐기의 차이
- 회전(Renew): 키 정보는 그대로 두고 평문만 새로 변경합니다. 키 유출이 의심되지만 설정은 계속 사용할 경우 적합하며, 반드시 사용처에 새로운 평문 키를 적용하세요.
- 폐기(Revoke): 키를 완전히 무효화하지만 기록은 남겨 감사 및 추적이 가능합니다. 더 이상 필요 없는 키에 적합합니다. 회전과 폐기 모두 추가 확인 절차가 필요합니다.
원클릭 테이크오버와의 관계
원클릭 테이크오버를 이용해 AI 도구를 게이트웨이에 연결하면, 해당 도구 전용 가상 키가 자동으로 생성되어 도구 설정에 입력됩니다. 또한 키 관리 페이지에서 이러한 자동 생성 키를 직접 관리할 수 있습니다.
자주 묻는 질문 (FAQ)
- Q: 평문 키를 복사하지 못했다면 어떻게 하나요?
- A: 평문 키는 다시 확인할 수 없습니다. 해당 키를 '회전'하여 새로 생성된 키로 앱의 설정을 교체하세요.
- Q: 폐기와 삭제는 어떻게 다른가요?
- A: 폐기는 키 기록을 남겨 (감사 목적) 보관하지만, 삭제는 완전히 기록에서 제거합니다. 둘 다 즉시 키를 무효화합니다.
- Q: '허용 모델'을 설정한 뒤 앱이 다른 모델을 요청하면 어떻게 되나요?
- A: 허용되지 않은 모델로 요청 시 게이트웨이가 해당 요청을 거부합니다. 앱에서 사용될 모델이 허용 리스트에 포함되었는지 확인하거나 제한을 해제하세요.
- Q: 속도 제한에 도달하면 어떻게 됩니까?
- A: RPM/TPM/RPD/TPD를 초과한 요청은 게이트웨이가 차단합니다. 통계 페이지에서 실제 사용량을 확인하고 상한선을 조절하세요.
요약
가상 키를 통해 최소 권한 부여와 완전한 키 관리를 실현할 수 있습니다. 모델/채널, 속도 제한 설정과 결합하면, 각 사용 목적에 맞는 인증 토큰을 세밀하게 배포 및 관리할 수 있습니다. 필요할 때마다 회전 또는 폐기가 가능하며, 실제 공급업체 API Key는 직접 노출되지 않습니다.
