TokenLab

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-token

Management tokens and API keys have different roles. Use mt-... only with /v1/management/*. Use sk-... with model APIs such as /v1/responses.

Endpoints

EndpointMethodUse
/v1/management/balanceGETGet the Workspace balance
/v1/management/api-keysGETList API keys
/v1/management/api-keysPOSTCreate an API key
/v1/management/api-keys/{keyId}PATCHChange its name, limit, models, expiration, or status
/v1/management/api-keys/{keyId}/usageGETGet individual usage records
/v1/management/api-keys/{keyId}/billingGETGet 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: null means unlimited. 0 prevents the key from incurring spend.
  • Amounts use USD. Sending CNY returns 400 currency_retired.
  • inactive can be enabled again. Use revoked to 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.

StatuscodeMeaning
400validation_errorA field or query parameter is invalid
400invalid_model_accessA model in models is not allowed by the Workspace's model policy
400currency_retiredlimitCurrency is CNY; use USD
401invalid_management_tokenThe token is missing, malformed, or revoked
403organization_inactiveThe Workspace is not active
404not_foundThe API key is not in this Workspace
409api_key_revokedA revoked key cannot be enabled again; create a new key
429report_busyToo 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"

Next

On this page