관리 API 를 사용하면 일반 추론용 API 키 없이도 조직 API 키를 관리하고 키 단위 사용량 및 과금 정보를 조회할 수 있습니다.
관리 토큰은 Dashboard 의 Settings 페이지에서 발급하고 교체할 수 있습니다.
Authorization: Bearer mt-your-management-token
관리 토큰은 추론용 API 키와 다릅니다. /v1/management/* 에는 mt-... 를, /v1/responses 같은 추론 엔드포인트에는 sk-... 를 사용하세요.
사용 가능한 엔드포인트
| Endpoint | Method | 설명 |
|---|
/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 | 페이지 크기 |
logicalModel | string | 최대 길이 100 | 요청된 논리 모델 이름 |
modelVendor | string | 최대 길이 100 | 공개 모델 공급자 |
scene | enum | - | chat, image, audio, video, embedding, rerank, translation, music, 3d |
accessChannel | enum | - | platform 또는 byok |
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 | null | 최소 0, 최대 100000 | null 또는 생략 = 무제한, 0 = 사용 가능 한도 0, 양수 = USD 사용 한도 |
limitCurrency | enum | 기본값 USD | 선택 사항: USD 또는 CNY. CNY로 설정하면 limitAmount를 RMB로 해석하고 저장 전에 서버에서 USD로 환산합니다 |
models | string[] | 기본값 [] | 선택적 논리 모델 허용 목록 |
expiresAt | string | null | RFC3339 datetime | null 은 만료 없음 의미 |
PATCH /v1/management/api-keys/
| 필드 | 타입 | 기본값 / 제한 | 설명 |
|---|
status | enum | - | active, inactive, revoked |
name | string | 길이 1-50 | 업데이트된 표시 이름 |
limitAmount | number | null | 최소 0, 최대 100000 | null = 무제한, 0 = 사용 가능 한도 0 |
limitCurrency | enum | 기본값 USD | 선택 사항: USD 또는 CNY. CNY로 설정하면 limitAmount를 RMB로 해석하고 저장 전에 서버에서 USD로 환산합니다 |
models | string[] | - | 업데이트된 논리 모델 허용 목록 |
expiresAt | string | null | RFC3339 datetime | null 은 만료 제거 |
금액 계약
- 기본적으로 요청의
limitAmount는 USD로 해석됩니다. limitCurrency: "CNY"를 설정하면 RMB 한도를 보낼 수 있고, 서버가 저장 전에 현재 환율로 USD로 변환합니다.
- 응답의 금액 필드는 원래 USD 값을 유지하면서
_cny 접미사가 붙은 RMB 표시값을 함께 제공합니다.
exchange_rate는 API Key 메타데이터와 함께 반환되며, 해당 응답의 각 *_cny 값에 사용된 USD→CNY 환율을 의미합니다.
리포팅 의미
logicalModel 은 호출자가 요청한 공개 논리 모델을 의미합니다.modelVendor 는 숨겨진 물리 라우트가 아니라 공개 모델 공급자를 의미합니다.scene 은 엔드포인트 또는 작업 유형에서 파생된 공개 요청 장면입니다.accessChannel=platform 은 해당 요청이 LemonData 플랫폼 채널을 통해 과금되었음을 의미합니다.accessChannel=byok 은 해당 요청이 사용자의 업스트림 공급자 키를 사용했음을 의미합니다.
응답에는 공개 가능한 과금 및 리포팅 필드만 포함되며, 내부 라우팅 세부 정보와 물리 공급자 메타데이터는 숨겨집니다.
billing 페이지네이션 참고
/usage 는 페이지네이션됩니다. /billing 은 현재 집계형 엔드포인트이므로 page / limit 형태의 페이지네이션 메타데이터를 반환하지 않습니다. 행 단위 상세 기록이 필요하다면 /usage 를 사용하세요.
빠른 예시
먼저 현재 관리 토큰으로 조회 가능한 API 키 목록을 확인하세요.
curl "https://api.lemondata.cc/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_cny": 3600.0,
"used_amount": 148.25,
"used_amount_cny": 1067.4,
"exchange_rate": 7.2,
"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"
}
]
}
다음 단계
