Overview
The Management API lets you manage organization API keys and retrieve usage and billing for a specific key without using a standard inference API key.
Use a management token from your Dashboard Settings page:
Authorization: Bearer mt-your-management-token
Management tokens are different from inference API keys. Use mt-... for /v1/management/*, and use sk-... for model inference endpoints such as /v1/responses.
Available Endpoints
| Endpoint | Method | Description |
|---|
/v1/management/api-keys | GET | List user-managed API keys in the current organization |
/v1/management/api-keys | POST | Create a new user API key |
/v1/management/api-keys/{keyId} | PATCH | Update name, usage limit, allowed models, expiry, or status |
/v1/management/api-keys/{keyId}/usage | GET | Retrieve paginated usage details for a specific key |
/v1/management/api-keys/{keyId}/billing | GET | Retrieve aggregated billing breakdowns for a specific key |
Usage Filter Contract
GET /v1/management/api-keys/{keyId}/usage supports the following query parameters:
| Parameter | Type | Default / Limits | Notes |
|---|
page | integer | default 1, min 1 | 1-based page number |
limit | integer | default 50, min 1, max 100 | Page size |
logicalModel | string | max length 100 | Requested logical model name |
modelVendor | string | max length 100 | Public model vendor |
scene | enum | - | chat, image, audio, video, embedding, rerank, translation, music, 3d |
accessChannel | enum | - | platform or byok |
startDate | string | - | Inclusive lower bound; accepts RFC3339 with timezone or YYYY-MM-DD |
endDate | string | - | Inclusive upper bound; accepts RFC3339 with timezone or YYYY-MM-DD |
startDate and endDate are present, startDate must be earlier than or equal to endDate.
API Key Body Contract
POST /v1/management/api-keys
| Field | Type | Default / Limits | Notes |
|---|
name | string | required, default Default Key, length 1-50 | Display name, trimmed server-side |
limitAmount | number | null | min 0, max 100000 | null or omitted = unlimited, 0 = zero quota, positive = USD spending cap |
limitCurrency | enum | default USD | Optional: USD or CNY. When set to CNY, limitAmount is treated as RMB and converted to USD server-side before storage |
models | string[] | default [] | Optional logical model allowlist |
expiresAt | string | null | RFC3339 datetime | null means no expiry |
PATCH /v1/management/api-keys/
| Field | Type | Default / Limits | Notes |
|---|
status | enum | - | active, inactive, revoked |
name | string | length 1-50 | Updated display name |
limitAmount | number | null | min 0, max 100000 | null means unlimited, 0 means zero quota |
limitCurrency | enum | default USD | Optional: USD or CNY. When set to CNY, limitAmount is treated as RMB and converted to USD server-side before storage |
models | string[] | - | Updated logical model allowlist |
expiresAt | string | null | RFC3339 datetime | null clears the expiry |
Monetary Contract
- By default, request-side
limitAmount is interpreted as USD. Set limitCurrency: "CNY" to submit an RMB cap; the server converts it to USD using the current exchange rate before storage.
- Response-side monetary fields keep the original USD field and add an RMB companion with
_cny.
exchange_rate is returned alongside API key metadata and is the USD→CNY rate used for every *_cny value in that response.
Reporting Semantics
logicalModel refers to the public logical model requested by the caller.modelVendor refers to the public model vendor, not the hidden physical route.scene is the public request scene derived from the endpoint or task type.accessChannel=platform means the request was billed via LemonData’s platform channel.accessChannel=byok means the request used your own upstream provider key.
Responses expose public billing and reporting fields only. Internal routing details and physical provider metadata remain hidden.
/usage is paginated. /billing is currently an aggregated breakdown endpoint and does not return page / limit style pagination metadata. If you need line-level records, use /usage.
Quick Example
Start by listing the API keys available to the current management token:
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"
}
]
}
Next Steps
