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-keyFor Anthropic-compatible /v1/messages requests, you can also use:
x-api-key: sk-your-api-keyGemini-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-tokenUse 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
- Sign in to TokenLab Console
- Open API Keys
- Create a new key
- Give it a descriptive name
- 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:
| Setting | Description |
|---|---|
| Spending limit | No limit lets the key use the Workspace balance. Fixed limit makes the key return 402 quota_exceeded after it reaches the amount. |
| Allowed models | The key can call only these models. Other models return 403 model_not_allowed. Empty means no key-level restriction. |
| Delivery option | Auto, Verified, or Official for requests from this key. Empty uses the Workspace default. See Billing and pricing. |
| Expiration | After this time the key returns 401 expired_api_key. |
| Status | An 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 Code | Type | Code | Description |
|---|---|---|---|
| 401 | invalid_api_key | invalid_api_key | The API key is missing, invalid, inactive, or revoked |
| 401 | expired_api_key | expired_api_key | The key has expired |
| 402 | insufficient_balance | insufficient_balance | Account balance is insufficient |
| 402 | quota_exceeded | quota_exceeded | API key usage limit reached |
| 403 | permission_error | model_not_allowed | The key is not allowed to use the requested model |
| 403 | permission_error | user_suspended, account_restricted | The account cannot use the API |
| 429 | rate_limit_exceeded | rate_limit_exceeded | Too 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"
}
}