문서
관리 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"end_date는 오늘로 읽으며, 응답에 실제로 사용한 종료일이 담깁니다.안전하게 보관하기
- 허용 목록을 설정하세요. 서버 주소에서만 작동하는 키는 도난당해도 쓸모가 거의 없습니다.
- 키는 도구를 실행하는 서버의 시크릿 저장소에 보관하세요. 브라우저, 모바일 앱, 저장소에는 절대 넣지 마세요.
- 유출되면 API 키 페이지 맨 아래에서, 또는 해당 키에
DELETE를 호출해 폐기하세요. 폐기 대화상자에서 그 키가 만든 키도 함께 폐기할 수 있습니다. - 키가 API로 한 모든 변경은 API 키 페이지의 ‘관리 키’ 아래에 시각, 요청 주소, 변경한 키와 함께 최근 50건까지 표시됩니다. 그 페이지에서 직접 한 변경은 표시되지 않습니다.
- 계정이 정지되거나 검토 중이 되면, 그리고 폐기되면 키는 저절로 작동을 멈춥니다.
관리 키는 분당 60번 요청할 수 있습니다. 변경마다 요청을 한 번씩 보내고, 목록은 키를 하나씩 읽지 말고 페이지 단위로 읽으세요.
관련 문서
그룹, 그룹의 월간 한도, 수치를 집계하는 방식은 키 그룹 페이지에서 설명합니다. 사용량 수치는 사용량 페이지와 같습니다.