Overview
The Management API lets you retrieve organization balance totals, 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/balance | GET | Retrieve current organization balance totals |
/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 Filters
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 |
model | string | max length 100 | Requested model name |
modelVendor | string | max length 100 | Public model vendor |
scene | enum | - | chat, image, audio, video, embedding, rerank, translation, music, 3d, realtime |
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 Request Body
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, input max 1000000 | null or omitted = unlimited, 0 = zero quota. Positive values are normalized to a stored cap that cannot exceed 100000 USD equivalent. |
limitCurrency | enum | default USD | USD only. Sending CNY returns 400 currency_retired. |
models | string[] | default [] | Optional 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, input max 1000000 | null means unlimited, 0 means zero quota. Positive values are normalized to a stored cap that cannot exceed 100000 USD equivalent. |
limitCurrency | enum | default USD | USD only. Sending CNY returns 400 currency_retired. |
models | string[] | - | Updated model allowlist |
expiresAt | string | null | RFC3339 datetime | null clears the expiry |
Monetary Fields
- Management API monetary request and response fields are USD-only.
limitCurrency defaults to USD; sending CNY returns 400 with currency_retired.
Reporting Semantics
model refers to the model requested by the caller.modelVendor refers to the public model vendor, not provider-specific execution details.scene is the public request scene derived from the endpoint or task type.accessChannel=platform means the request was billed via TokenLab’s platform channel.accessChannel=byok means the request used your own provider key.
Responses expose public billing and reporting fields only. Provider execution details are not included in management responses.
/usage line items can include billing_transaction_id once the underlying request has reached settled billing state. Use request_id + billing_transaction_id for request-level reconciliation.
/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
First check the current organization balance with the management token:
curl -X GET "https://api.tokenlab.sh/v1/management/balance" \
-H "Authorization: Bearer mt-your-management-token"
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"
}
],
"pagination": {
"page": 1,
"limit": 50,
"total": 1,
"totalPages": 1
}
}
Next Steps
