관리
관리 API
관리 토큰으로 조직 잔액, 조직 API 키, 키 단위 사용량 및 과금 정보를 관리하고 조회합니다.
개요
Management API 는 일반 추론용 API 키를 쓰지 않고도 조직 잔액을 조회하고, 조직 API 키를 관리하며, 특정 키의 사용량과 과금을 조회할 수 있게 해줍니다.
Dashboard → API → Management Tokens에서 관리 토큰을 생성하세요:
Authorization: Bearer mt-your-management-token관리 토큰은 추론용 API 키와 다릅니다. /v1/management/* 에는 mt-... 를, /v1/responses 같은 모델 추론 엔드포인트에는 sk-... 를 사용하세요.
사용 가능한 엔드포인트
| 엔드포인트 | 메서드 | 설명 |
|---|---|---|
/v1/management/balance | GET | 현재 조직 잔액 합계 조회 |
/v1/management/api-keys | GET | 현재 조직에서 관리되는 사용자 API 키 목록 조회 |
/v1/management/api-keys | POST | 새 사용자 API 키 생성 |
/v1/management/api-keys/{keyId} | PATCH | 이름, 사용 한도, 허용 모델, 만료, 상태 업데이트 |
/v1/management/api-keys/{keyId}/usage | GET | 특정 키의 페이지네이션된 사용 상세 조회 |
/v1/management/api-keys/{keyId}/billing | GET | 특정 키의 집계 과금 내역 조회 |
사용 필터 계약
GET /v1/management/api-keys/{keyId}/usage 는 다음 query 파라미터를 지원합니다.
| 파라미터 | 타입 | 기본값 / 제한 | 설명 |
|---|---|---|---|
page | integer | 기본값 1, 최소 1 | 1부터 시작하는 페이지 번호 |
limit | integer | 기본값 50, 최소 1, 최대 100 | 페이지 크기 |
model | string | 최대 길이 100 | 호출자가 요청한 공개 모델 이름 |
modelVendor | string | 최대 길이 100 | 공개 모델 공급자 |
scene | enum | - | chat, image, audio, video, embedding, rerank, translation, music, 3d, realtime |
startDate | string | - | 포함 시작 경계값. 타임존이 포함된 RFC3339 또는 YYYY-MM-DD 를 지원합니다 |
endDate | string | - | 포함 종료 경계값. 타임존이 포함된 RFC3339 또는 YYYY-MM-DD 를 지원합니다 |
startDate 와 endDate 를 함께 보내는 경우 startDate 는 endDate 보다 빠르거나 같아야 합니다.
API 키 본문 계약
POST /v1/management/api-keys
| 필드 | 타입 | 기본값 / 제한 | 설명 |
|---|---|---|---|
name | string | 선택 사항, 기본값 Default Key, 길이 1-50 | 표시 이름이며 서버에서 앞뒤 공백을 제거합니다 |
limitAmount | number | string | null | 0–100000 USD | null은 무제한, 0은 지출 불가입니다. 10진 문자열은 소수점 아래 6자리까지 지원합니다. 키 생성 시 생략하면 무제한입니다. |
limitCurrency | enum | 기본값 USD | USD만 지원됩니다. CNY를 보내면 400 currency_retired가 반환됩니다. |
models | string[] | 기본값 [] | 선택적 모델 허용 목록 |
deliveryPolicy | string | null | auto, verified, official, null | null은 워크스페이스의 전달 정책을 상속합니다. |
expiresAt | string | null | RFC3339 datetime | null 은 만료 없음 의미 |
PATCH /v1/management/api-keys/{keyId}
| 필드 | 타입 | 기본값 / 제한 | 설명 |
|---|---|---|---|
status | enum | - | active, inactive, revoked |
name | string | 길이 1-50 | 업데이트된 표시 이름 |
limitAmount | number | string | null | 0–100000 USD | null은 무제한, 0은 지출 불가입니다. 10진 문자열은 소수점 아래 6자리까지 지원합니다. |
limitCurrency | enum | 기본값 USD | USD만 지원됩니다. CNY를 보내면 400 currency_retired가 반환됩니다. 지정하면 limitAmount도 필요합니다. |
models | string[] | - | 업데이트된 모델 허용 목록 |
deliveryPolicy | string | null | auto, verified, official, null | null은 워크스페이스의 전달 정책을 상속합니다. |
expiresAt | string | null | RFC3339 datetime | null 은 만료 제거 |
PATCH 요청에는 최소 1개 이상의 필드가 포함되어야 합니다.
금액 필드
- Management API의 금액 요청 및 응답 필드는 USD만 지원합니다.
limitCurrency의 기본값은USD입니다.CNY를 보내면400 currency_retired가 반환됩니다.
리포팅 의미
model은 호출자가 요청한 공개 모델을 의미합니다.modelVendor는 숨겨진 호환 경로가 아니라 공개 모델 공급자를 의미합니다.scene은 엔드포인트 또는 작업 유형에서 파생된 공개 요청 장면입니다.
응답에는 공개 가능한 과금 및 리포팅 필드만 포함되며, 내부 라우팅 세부 정보와 물리 공급자 메타데이터는 숨겨집니다.
/usage개별 항목은 기본 요청의 정산이 완료되면billing_transaction_id를 포함할 수 있습니다. 요청 단위 대조에는request_id와billing_transaction_id를 함께 사용하세요.
청구 페이지네이션 참고
/usage 는 페이지네이션됩니다. /billing 은 현재 집계형 엔드포인트이므로 page / limit 형태의 페이지네이션 메타데이터를 반환하지 않습니다. 행 단위 상세 기록이 필요하다면 /usage 를 사용하세요.
빠른 예시
먼저 현재 관리 토큰으로 조직 잔액을 확인하세요.
요청
curl -X GET "https://api.tokenlab.sh/v1/management/balance" \
-H "Authorization: Bearer mt-your-management-token"이어서 같은 관리 토큰으로 조회 가능한 API 키 목록을 확인하세요.
요청
curl "https://api.tokenlab.sh/v1/management/api-keys" \
-H "Authorization: Bearer mt-your-management-token"응답
{
"object": "list",
"data": [
{
"id": "key_abc123def456",
"name": "Backend Worker",
"key_prefix": "sk-abc123...",
"status": "active",
"limit_amount": 500.0,
"limit_amount_decimal": "500",
"used_amount": 148.25,
"used_amount_decimal": "148.25",
"models": [
"gpt-4o-mini",
"claude-3-7-sonnet"
],
"expires_at": "2026-04-30T00:00:00.000Z",
"last_used_at": "2026-03-27T08:12:45.000Z",
"created_at": "2026-03-01T10:00:00.000Z",
"delivery_policy": null
}
],
"pagination": {
"page": 1,
"limit": 50,
"total": 1,
"totalPages": 1
}
}