TokenLab

Getting Started

Authentication

Authenticate TokenLab API requests with an API key

API Keys

Model calls and private resources require an API key. Public discovery endpoints such as GET /v1/models and GET /v1/models/{model} work without one. A successful discovery response does not verify that your key works; follow the Quickstart to send a model request. Use the complete saved key; the prefix in the key list cannot authenticate.

For OpenAI-compatible endpoints, send it as:

Authorization: Bearer sk-your-api-key

For Anthropic-compatible /v1/messages requests, you can also use:

x-api-key: sk-your-api-key

Gemini-compatible /v1beta/* requests also accept x-goog-api-key: sk-your-api-key. Prefer a header over the ?key= query parameter, because URLs often end up in logs.

Management Tokens

Management API endpoints use a separate token type:

Authorization: Bearer mt-your-management-token

Use management tokens only with /v1/management/* endpoints. Open API → Tokens for the selected workspace to create or replace a token. Save the full token when it is shown; it is displayed only once after creation or replacement.

Management tokens cannot be used for model inference, and standard sk-... API keys cannot be used for the Management API.

Get an API key

  1. Sign in to TokenLab Console
  2. Open API Keys
  3. Create a new key
  4. Give it a descriptive name
  5. Copy it immediately because it is shown only once
  • Never expose API keys in client-side code
  • Never commit API keys to version control
  • Use environment variables or a secret manager
  • Rotate keys periodically
  • Delete unused keys

Use an API key

See the Quickstart for environment variables and a complete first request. Use the SDK matching your chosen API format; keep keys on the server.

Key settings

You can set these on each API key in Console, and through the Management API:

SettingDescription
Spending limitNo limit lets the key use the Workspace balance. Fixed limit makes the key return 402 quota_exceeded after it reaches the amount.
Allowed modelsThe key can call only these models. Other models return 403 model_not_allowed. Empty means no key-level restriction.
Delivery optionAuto, Verified, or Official for requests from this key. Empty uses the Workspace default. See Billing and pricing.
ExpirationAfter this time the key returns 401 expired_api_key.
StatusAn inactive (paused) key returns 401 invalid_api_key. A revoked key cannot be enabled again.

Key prefix

All TokenLab API keys start with sk-.

Error Responses

Status CodeTypeCodeDescription
401invalid_api_keyinvalid_api_keyThe API key is missing, invalid, inactive, or revoked
401expired_api_keyexpired_api_keyThe key has expired
402insufficient_balanceinsufficient_balanceAccount balance is insufficient
402quota_exceededquota_exceededAPI key usage limit reached
403permission_errormodel_not_allowedThe key is not allowed to use the requested model
403permission_erroruser_suspended, account_restrictedThe account cannot use the API
429rate_limit_exceededrate_limit_exceededToo many failed authentication attempts from one IP address. Wait for Retry-After and fix the key; do not loop on 401

Example:

{
  "error": {
    "message": "Invalid API key",
    "type": "invalid_api_key",
    "code": "invalid_api_key"
  }
}

On this page