서버리스 키 관리

서버리스 키 예산은 발급하는 순간 팀 크레딧에서 선불로 빠진다. 증액은 추가 구매, 감액·폐기는 잔여 환원이다(D-028).

언제 쓰나

• 팀에 OpenAI 호환 서버리스 API 키를 발급할 때
• 키 예산·모델·호출 한도를 조정할 때
• 키를 폐기하고 남은 예산을 팀 크레딧으로 되돌릴 때

화면

서버리스 키 목록

요소	설명
키 목록 활성 N / 전체	활성 키 수와 전체 키 수
키 열	별칭과 마스킹된 키(sk-…). 발급 직후에는 발급 대기
팀 열	키 소유 팀
모델 열	접근 허용된 모델 수
예산/사용 열	사용 / 예산 C와 소진 게이지
상태 열	pending_purchase / 수령 대기 / 활성 / 차단 / 폐기
폐기	폐기하지 않은 키에만 표시된다

새 키 발급을 누르면 구성 입력 모달이 뜬다.

새 키 발급

입력	설명
팀	키를 받을 팀. 라벨에 할당 가능 잔여 … C가 함께 표시된다
키 예산 (C)	발급 즉시 선불 차감될 금액. 기본 3,000
별칭	팀 안에서 유일한 키 이름
모델 접근	체크한 모델만 이 키로 호출 가능. 1K 토큰당 입력/출력 단가가 옆에 표시된다
TPM 제한 / RPM 제한	분당 토큰·요청 상한. 기본 200,000 / 120

모달 하단에 팀 키 예산 합계는 팀 예산을 넘을 수 없습니다가 상시 안내된다.

절차

키 발급

1. 새 키 발급을 누르고 팀을 고른다. 별칭이 팀 이름 기반으로 자동 채워진다.
2. 키 예산을 정한다. 팀의 미폐기 키 예산 합계 + 이 예산이 팀 예산을 넘으면 입력란이 빨갛게 되고 발급이 막힌다(D-018).
3. 모델과 한도를 정하고 발급을 누른다.
4. 내부적으로 두 단계로 처리된다.
   • 키를 pending_purchase로 먼저 확정한다.
   • 팀 크레딧에서 예산만큼 선불 차감하고(원장 serverless_purchase) 상태를 수령 대기(pending_claim)로 올린다.
5. 팀에 서버리스 API 키가 준비되었습니다 알림이 간다. 비밀 키는 팀이 수령할 때 생성되어 팀에게만 한 번 표시된다. 관리자는 평문을 볼 수 없다(D-010).

예산 증액·감액

1. 키 행에서 예산을 수정한다.
2. 증액: 차액만큼 팀 크레딧에서 추가 구매(차감)한다.
3. 감액: 차액을 팀 크레딧으로 환원한다. 단 이미 사용한 금액 아래로는 감액할 수 없다(budget_below_used).
4. 차단 상태였던 키가 예산 증액으로 사용 여력이 생기면 활성으로 돌아온다.

폐기·환원

1. 키 행의 폐기를 누른다. 확인 모달에 폐기 즉시 이 키의 모든 호출이 401로 거부됩니다가 뜬다.
2. 폐기를 확정하면:
   • 잔여 예산(예산 − 사용)이 팀 크레딧으로 환원된다(원장 serverless_refund).
   • 환원액은 구매액에서 이미 환원한 액을 뺀 값을 넘을 수 없다. 구매하지 않은 예산은 환원되지 않는다(ck_llmkey_prepaid_nonneg).
   • 상태가 폐기로 바뀌고 게이트웨이 캐시가 즉시 무효화되어 그 키의 호출이 401이 된다.

이렇게 되면 정상

• 발급: 목록에 수령 대기 키가 생기고 크레딧·정산에 서버리스 키 구매 (선불) 차감이 남는다. 팀 잔여가 예산만큼 준다.
• 증액: 서버리스 키 구매 (선불)가 차액만큼 추가로 남는다.
• 감액·폐기: 서버리스 키 환원이 남고 팀 잔여가 그만큼 는다.
• 폐기된 키로 호출하면 401, 예산을 넘긴 키는 429가 반환된다.

막히는 경우

증상	원인	조치
예산 입력란이 빨갛고 발급 비활성	팀 키 예산 합계가 팀 예산 초과(D-018)	팀 예산을 증액하거나 키 예산을 낮춘다
insufficient_credit	발급·증액 시 팀 크레딧 부족	팀 예산을 먼저 증액한다
alias_budget_mismatch	같은 이름의 미폐기 키가 다른 예산으로 존재	기존 키를 폐기 후 재발급하거나 그 키를 수정
budget_below_used	사용분보다 낮게 감액 시도	사용액 이상으로만 감액
already_revoked	이미 폐기된 키를 폐기·수정 시도	목록을 새로고침한다
key_create_conflict	동시 발급 경합	잠시 후 다시 시도한다
발급 응답이 유실됐다	네트워크 문제	같은 팀·별칭·예산으로 재시도하면 이중 차감되지 않는다. 예산이 다르면 alias_budget_mismatch로 막힌다

알아둘 것

• 게이트웨이는 호출당 원장을 차감하지 않는다. 예산은 발급 때 이미 빠졌고, 호출 시에는 사용 카운터와 사용 이벤트만 기록한다. 호출당 차감 방식(usage_llm)은 레거시다.
• 비밀 키는 팀이 수령하는 순간 생성된다. 발급 직후 목록의 발급 대기는 아직 비밀이 없는 상태다.
• 키 상태 흐름: pending_purchase(차감 대기) → pending_claim(수령 대기) → active → 예산 초과 시 blocked → revoked.
• 환원은 구매를 초과할 수 없다는 게 DB 제약으로 박혀 있다. 감액과 폐기를 반복해도 넣은 것보다 많이 돌려받을 수 없다.
• 팀 키 예산 합계 한도(D-018)는 검증 한도이지 원장 hold가 아니다. 지출의 진실은 여전히 팀 계정 잔액이다.