Management API

curl -X GET "https://api.tokenlab.sh/v1/management/balance" \
  -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
  }
}

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

If both 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

At least one PATCH field must be provided.

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.

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.

Billing Pagination Note

/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"

Then list the API keys available to the same 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

Stream Generate Content Get Organization Balance

Core

Text

Files & Batches

Images

Audio & Realtime

Music

Video & Materials

Worlds

3D

Async Jobs

Gemini Native

Management

Overview

Available Endpoints

Usage Filters

API Key Request Body

POST /v1/management/api-keys

PATCH /v1/management/api-keys/

Monetary Fields

Reporting Semantics

Quick Example

Next Steps

​Overview

​Available Endpoints

​Usage Filters

​API Key Request Body

​POST /v1/management/api-keys

​PATCH /v1/management/api-keys/

​Monetary Fields

​Reporting Semantics

​Billing Pagination Note

​Quick Example

​Next Steps

Overview

Available Endpoints

Usage Filters

API Key Request Body

POST /v1/management/api-keys

PATCH /v1/management/api-keys/

Monetary Fields

Reporting Semantics

Billing Pagination Note

Quick Example

Next Steps