Management
Management API
Check Workspace balances, manage API keys, and retrieve usage and billing
Use the Management API from your own backend or automation to manage a TokenLab Workspace. It uses a management token, so the program does not need a regular API key.
Create a management token in Dashboard → API → Management Tokens:
Authorization: Bearer mt-your-management-tokenManagement tokens and API keys have different roles. Use mt-... only with /v1/management/*. Use sk-... with model APIs such as /v1/responses.
Endpoints
| Endpoint | Method | Use |
|---|---|---|
/v1/management/balance | GET | Get the Workspace balance |
/v1/management/api-keys | GET | List API keys |
/v1/management/api-keys | POST | Create an API key |
/v1/management/api-keys/{keyId} | PATCH | Change its name, limit, models, expiration, or status |
/v1/management/api-keys/{keyId}/usage | GET | Get individual usage records |
/v1/management/api-keys/{keyId}/billing | GET | Get a billing summary |
API Keys
- A new key's full secret appears only in the create response.
models: []adds no key-level model restriction.limitAmount: nullmeans unlimited.0prevents the key from incurring spend.- Amounts use USD. Sending
CNYreturns400 currency_retired. inactivecan be enabled again. Userevokedto retire a key permanently.
Usage and Billing
/usage returns paginated records and supports model, model maker, scene, and date filters. Settled records can include billing_transaction_id; save it with request_id when you need to match a charge to a request.
/billing returns totals grouped by model, model maker, scene, and date. It does not include Workspace top-ups or invoices.
A date-only endDate such as 2026-07-31 means 00:00 UTC at the start of that day. To include the whole day, pass the next date or an RFC3339 time such as 2026-07-31T23:59:59Z.
Errors
Errors use the standard error object. Handle them by status and code.
| Status | code | Meaning |
|---|---|---|
| 400 | validation_error | A field or query parameter is invalid |
| 400 | invalid_model_access | A model in models is not allowed by the Workspace's model policy |
| 400 | currency_retired | limitCurrency is CNY; use USD |
| 401 | invalid_management_token | The token is missing, malformed, or revoked |
| 403 | organization_inactive | The Workspace is not active |
| 404 | not_found | The API key is not in this Workspace |
| 409 | api_key_revoked | A revoked key cannot be enabled again; create a new key |
| 429 | report_busy | Too many usage or billing reports are running. Retry after the Retry-After seconds |
Example
curl "https://api.tokenlab.sh/v1/management/balance" \
-H "Authorization: Bearer mt-your-management-token"