TokenLab Management API Adds Workspace Balance Lookup

Letting an automated production pipeline stall on an empty balance is preventable. The TokenLab Management API balance lookup provides automated workflows with a queryable balance total using a management token rather than an inference key.

This guide covers the GET /v1/management/balance endpoint contract, authentication requirements, currency handling, and how to verify response schemas directly against official documentation.

Key Takeaways

Management Tokens vs. Model Inference API Keys

Management tokens and model inference keys fulfill distinct operational roles in TokenLab:

• Model inference API keys (sk-...): Used to call inference endpoints such as POST /v1/chat/completions, POST /v1/responses, native Anthropic Messages on POST /v1/messages, and Gemini on /v1beta/models/.... These keys execute generation requests but do not expose organization-level financial data.
• Management tokens (mt-...): Restricted to /v1/management/* routes. They allow backends to inspect workspace balances, list or edit API keys, and monitor usage without granting model generation access.

Separating these credentials ensures bookkeeping scripts and finance monitors cannot trigger billable inference calls, while model workers never gain access to account administration.

The Balance Endpoint Wire Contract

Send a GET request to https://api.tokenlab.sh/v1/management/balance authenticating with your management token in the Authorization header:

curl -X GET "https://api.tokenlab.sh/v1/management/balance" \
  -H "Authorization: Bearer mt-your-management-token"

Response Schema

A successful request returns 200 OK with an organization_balance object:

{
  "object": "organization_balance",
  "organization_id": "org_123",
  "balance": 42.5,
  "balance_decimal": "42.50",
  "total_recharge": 100,
  "total_recharge_decimal": "100",
  "total_used": 57.5,
  "total_used_decimal": "57.50"
}

Response Fields

• object (string): Always organization_balance.
• organization_id (string): Organization associated with the current management token.
• balance (number): Current workspace balance in USD as a floating-point number for display.
• balance_decimal (string): Exact current workspace balance in USD formatted as a decimal string for financial reconciliation.
• total_recharge (number): Total successful workspace recharge amount in USD.
• total_recharge_decimal (string): Exact total successful workspace recharge amount in USD formatted as a decimal string.
• total_used (number): Total workspace usage spend in USD.
• total_used_decimal (string): Exact total workspace usage spend in USD formatted as a decimal string.

Monetary fields are strictly USD. When parsing balance programmatically for threshold checks or ledger reconciliation, parse balance_decimal with an arbitrary-precision decimal library rather than floating-point primitives to prevent precision loss.

Implementing Balance Checks

Common integration patterns include:

1. Pre-Batch Guardrails: Before dispatching large workloads—such as high-volume generation on models like gpt-5.5 or glm-5.2—query /v1/management/balance. If balance_decimal falls below the estimated batch cost, pause the job queue.
2. Low-Balance Alerts: While automated email notifications can be configured under Console → Settings, a scheduled monitoring cron can poll the endpoint and trigger internal Slack, PagerDuty, or webhook notifications.
3. Billing Reconciliation: Combine the live workspace balance with individual key usage records (/v1/management/api-keys/{keyId}/usage) to reconcile token expenditures against settled invoice lines.

For full endpoint specifications and key management methods, review the Get Workspace Balance API Reference and the Management API Overview.