Skip to content

authentication.mdx

Latest commit

 

History

History
141 lines (105 loc) · 3.26 KB

authentication.mdx

File metadata and controls

141 lines (105 loc) · 3.26 KB
Raw
title Authentication
description Secure your TokenLab API requests with API keys

API Keys

All TokenLab API requests require an API key.

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

Management Tokens

Management API endpoints use a separate token type:

Authorization: Bearer mt-your-management-token

Use management tokens only with /v1/management/* endpoints. They are created from the Settings page in your Dashboard and are shown in full only once when generated or rotated.

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

Getting Your API Key

  1. Log in to your TokenLab Dashboard
  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

Using API Keys

curl https://api.tokenlab.sh/v1/responses \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4",
    "input": "Hello!"
  }'
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("TOKENLAB_API_KEY"),
    base_url="https://api.tokenlab.sh/v1"
)
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.TOKENLAB_API_KEY,
  baseURL: 'https://api.tokenlab.sh/v1'
});

API Key Features

Usage Limits

You can set a usage limit on each API key:

Setting Description
No Limit Key uses your account balance without restrictions
Fixed Limit Key stops working after reaching the specified amount

Key Prefix

All TokenLab API keys start with sk-.

Anthropic Compatibility

For the /v1/messages endpoint, the Anthropic-style header works as expected:

curl https://api.tokenlab.sh/v1/messages \
  -H "x-api-key: sk-your-api-key" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello!"}]
  }'
Use `Authorization: Bearer ...` for OpenAI-compatible endpoints such as `/v1/responses`, `/v1/chat/completions`, `/v1/models`, and most other TokenLab routes.

Error Responses

Status Code Type Code Description
401 invalid_api_key invalid_api_key Missing or invalid API key
401 expired_api_key expired_api_key API key has been revoked
402 insufficient_balance insufficient_balance Account balance is insufficient
402 quota_exceeded quota_exceeded API key usage limit reached

Example:

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