문서

문서

관리 API

관리 키를 사용하면 직접 만든 시스템이 계정의 API 키를 만들고, 그룹으로 묶고, 한도를 두고, 폐기하며 각 키의 지출도 API로 조회할 수 있습니다. 모델은 호출할 수 없습니다.

용도

일부 연동에서는 고객, 팀, 사용자마다 전용 API 키를 발급하고, 고객별 키를 그룹으로 묶고, 그룹이 쓸 수 있는 금액에 상한을 두며, 비용을 키별 또는 그룹별로 다시 읽어 옵니다. 키가 몇 개뿐이라면 API 키 페이지에서 하면 충분합니다. 키가 많다면 관리 키로 스크립트나 자체 관리 도구에서 API를 통해 같은 작업을 할 수 있습니다.

관리 키는 API 키와는 다른 자격 증명입니다. API 키를 받는 곳에서는 받아들여지지 않으며, /v1/chat/completions, /v1/messages 등 어떤 모델 경로도 호출할 수 없습니다. 관리 키는 /v1/management/에서만 작동하고, API 키는 거기서 작동하지 않습니다.

관리 키 만들기

  • API 키 페이지를 열고 맨 아래로 이동합니다. ‘관리 키’ 아래에서 ‘새 관리 키’를 선택합니다. 이 블록은 열기 전까지 접혀 있습니다.
  • 키 이름을 정합니다(예: 청구 동기화). 그러면 페이지에서 어떤 프로그램이 각 변경을 했는지 알 수 있습니다.
  • 호출을 허용할 주소를 한 줄에 하나씩 입력합니다. 203.0.113.7 같은 단일 주소나 203.0.113.0/24 같은 범위를 쓸 수 있습니다. 허용 목록이 없으면 키를 가진 사람은 누구나 사용할 수 있으며, 목록을 비워 두면 대화상자가 경고합니다.
  • 키가 표시되면 복사하세요. 한 번만 표시되며, Kunavo는 해시만 보관합니다.

계정에는 활성 관리 키를 동시에 두 개까지 둘 수 있습니다. 다른 키를 만들려면 하나를 폐기하세요.

호출하기

키를 Bearer 토큰으로 https://api.kunavo.com/v1/management에 보냅니다. 관리 키는 브라우저에서 호출할 수 없습니다. 응답에 CORS 헤더가 없으므로 다른 사이트의 페이지는 호출할 수 없습니다. 키는 서버에 두고 프런트엔드 코드에는 절대 넣지 마세요.

curl https://api.kunavo.com/v1/management/groups \
  -H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY"

응답은 JSON입니다. 오류는 나머지 API와 같은 형식으로, error 객체에 message, type, code, 해당하는 경우 잘못된 param가 담깁니다. 만나게 되는 상태는 다음과 같습니다.

상태의미
401키가 없거나, 잘못 입력했거나, 폐기되었거나, 계정이 정지되었거나 검토 중입니다.
403키에 IP 허용 목록이 있는데 요청이 목록에 없는 주소에서 왔습니다.
404그룹이나 키가 없거나, 삭제되었거나, 다른 계정에 속합니다. 세 경우 모두 같은 응답을 하므로 다른 계정의 ID로는 아무것도 알 수 없습니다.
409변경이 계정의 상태와 충돌합니다. 이미 쓰는 그룹 이름, 폐기된 키, 또는 활성 키 500개라는 계정 상한에 도달한 경우입니다.
429이 키가 지난 1분 동안 60번 요청했습니다. Retry-After 헤더가 몇 초를 기다려야 하는지 알려 줍니다.

그룹

GET /v1/management/groups는 계정의 그룹을 각 그룹의 월간 한도와 활성 키 수와 함께 나열합니다. POST는 그룹을 만들며, monthly_limit_usd는 선택 사항입니다. 이미 쓰는 이름이면 409입니다. PATCH /v1/management/groups/{id}는 이름이나 한도를 바꿉니다. 한도를 없애려면 null를 보내고, 0을 보내면 키를 폐기하지 않고 그룹의 모든 키를 일시 중지합니다. DELETE는 그룹을 삭제하며, 그 그룹의 호출은 사용량 페이지에 그룹 이름으로 남습니다. 그룹의 키는 활성 상태로 남아 그룹 없는 키가 되며, ?revoke_keys=true를 추가하면 키도 함께 폐기됩니다.

curl https://api.kunavo.com/v1/management/groups \
  -H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "CID000001", "monthly_limit_usd": 50}'

키

GET /v1/management/keys는 키를 최신순으로 나열합니다. 한 페이지에 키 50개가 담기며 limit로 최대 100개까지 늘릴 수 있습니다. status의 기본값은 active이고 revoked 또는 all도 쓸 수 있으며, group_id는 목록을 한 그룹으로 좁힙니다. has_more가 true이면 next_after를 after로 전달해 다음 페이지를 읽습니다. 키의 평문은 목록에 나오지 않습니다.

POST /v1/management/keys는 이름과, 선택적으로 group_id, monthly_limit_usd, ip_allowlist를 지정해 키를 만듭니다. 응답의 key 필드에 평문이 한 번만 담깁니다. POST를 반복하면 키가 하나 더 만들어지므로, 재시도하기 전에 키 목록에서 그 이름을 찾아보세요.

curl https://api.kunavo.com/v1/management/keys \
  -H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "CID000001_user1", "group_id": "GROUP_ID", "monthly_limit_usd": 20}'

PATCH /v1/management/keys/{id}는 키의 이름, 그룹, 한도, 허용 목록을 바꿉니다. group_id가 null이면 키가 그룹에서 빠집니다. DELETE는 키를 폐기합니다. 이미 폐기된 키를 다시 폐기해도 오류가 아닙니다. 폐기된 키는 변경할 수 없습니다.

curl -X DELETE https://api.kunavo.com/v1/management/keys/KEY_ID \
  -H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY"

사용량

GET /v1/management/usage는 계정 전체의 사용량을 최대 90 UTC 일 동안 보고하며, GET /v1/usage는 키 하나의 사용량을 보고합니다. group_by는 group, api_key, model, day를 어떻게 조합해도 되고 기본값은 api_key입니다. 수치의 의미는 사용량 페이지와 같습니다. 호출은 호출 당시 키가 속해 있던 그룹으로 집계되고, 실패한 호출은 비용이 들지 않으며, 한 기간의 합계는 같은 날짜의 CSV 내보내기와 1센트까지 일치합니다. group_id와 api_key_id는 보고서를 한 그룹 또는 한 키로 좁힙니다.

curl "https://api.kunavo.com/v1/management/usage?start_date=2026-10-01&end_date=2026-10-31&group_by=group,api_key" \
  -H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY"
날짜는 UTC 달력 기준 일이며 양 끝을 포함합니다. 오늘 이후의 end_date는 오늘로 읽으며, 응답에 실제로 사용한 종료일이 담깁니다.

안전하게 보관하기

  • 허용 목록을 설정하세요. 서버 주소에서만 작동하는 키는 도난당해도 쓸모가 거의 없습니다.
  • 키는 도구를 실행하는 서버의 시크릿 저장소에 보관하세요. 브라우저, 모바일 앱, 저장소에는 절대 넣지 마세요.
  • 유출되면 API 키 페이지 맨 아래에서, 또는 해당 키에 DELETE를 호출해 폐기하세요. 폐기 대화상자에서 그 키가 만든 키도 함께 폐기할 수 있습니다.
  • 키가 API로 한 모든 변경은 API 키 페이지의 ‘관리 키’ 아래에 시각, 요청 주소, 변경한 키와 함께 최근 50건까지 표시됩니다. 그 페이지에서 직접 한 변경은 표시되지 않습니다.
  • 계정이 정지되거나 검토 중이 되면, 그리고 폐기되면 키는 저절로 작동을 멈춥니다.

관리 키는 분당 60번 요청할 수 있습니다. 변경마다 요청을 한 번씩 보내고, 목록은 키를 하나씩 읽지 말고 페이지 단위로 읽으세요.

그룹, 그룹의 월간 한도, 수치를 집계하는 방식은 키 그룹 페이지에서 설명합니다. 사용량 수치는 사용량 페이지와 같습니다.