Authentication

Which key does what, how to protect, limit and replace it, and what its failures mean.

Two kinds of keys

New keys start with sk-tl-v1-. Existing sk-eu- keys remain valid. Both kinds of key are secrets, sent as Authorization: Bearer <key> over HTTPS.

Inference keyManagement key
PurposeCalls models.Manages the organization's inference keys and reads its credit.
EndpointThe gateway, /v1/...The Management API on the dashboard host, /api/...
Created inAPI Keys, by owners, admins and developers.Management keys, by owners and admins.
Belongs toOne workspace.The organization.
Scopesnonekeys:read, keys:write, workspaces:read, credits:read
VariableTOKENLANE_API_KEYTOKENLANE_MANAGEMENT_KEY

Neither can do the other's job: a management key cannot call models, an inference key cannot manage the account. Dashboard sign-in uses a browser session, not a key.

Keep the secret secret

A key is shown once and only its hash is stored; a lost key is replaced, not recovered.

  • Read it from the environment or secret manager of your server.
  • Never put it in browser or mobile app code, URLs, source control, logs, support messages or shared notebooks.
  • Use one key per application and environment.
  • If a key leaks, disable it at once and create a new one. The sk-tl-v1- prefix helps secret scanners find leaked keys.

Limit a key

Rules belong to the key: set them under Advanced or as policy through the Management API. Changes reach the gateway within seconds.

The gateway also enforces inherited organization and workspace rules. Each level may narrow models, providers and processing requirements; a request cannot broaden the intersection. Workspace budgets apply across all their inference keys. The console shows effective rules with their origin; see Organizations and workspaces.

RuleEffectFailure
expires_atRejects the key from that moment; running requests and streams finish.401 authentication
limit, limit_resetEUR budget, optionally reset daily, weekly (from Monday) or monthly in UTC.402 insufficient_credits when the rest cannot cover a request
allowed_modelsModel IDs or * patterns. Fallbacks outside the list are skipped.403 permission_denied; remedy_hint names the allowed models
server_toolsweb_search allows the web plugin.403 permission_denied
captureStores this key's prompts and answers for later retrieval.none

Replace a key

There is no rotate button. Instead:

  1. Create the new key in the same workspace with the same rules.
  2. Deploy it, and watch Last Used on the old one.
  3. Disable the old key: it is rejected within seconds and can be enabled again.
  4. Delete it once you are sure; generations made with it keep its key ID.

Automate with a management key

The Management API lives on the dashboard host, not on the gateway. This request lists the organization's keys: names, prefixes, policies and usage, never a secret.

curl

curl --request GET \
  --url 'https://tokenlane.de/api/keys' \
  --header 'Authorization: Bearer YOUR_MANAGEMENT_KEY'

node

const response = await fetch("https://tokenlane.de/api/keys", {
  method: "GET",
  headers: {
    "Authorization": "Bearer " + process.env.TOKENLANE_MANAGEMENT_KEY,
  },
});
console.log(await response.text());

python

import os
import urllib.request

request = urllib.request.Request(
    "https://tokenlane.de/api/keys",
    method="GET",
    headers={
        "Authorization": "Bearer " + os.environ["TOKENLANE_MANAGEMENT_KEY"],
    },
)

with urllib.request.urlopen(request) as response:
    print(response.read().decode("utf-8"))

vercel

// This operation uses HTTP directly.
const response = await fetch("https://tokenlane.de/api/keys", {
  method: "GET",
  headers: {
    "Authorization": "Bearer " + process.env.TOKENLANE_MANAGEMENT_KEY,
  },
});
console.log(await response.text());

A management key cannot create workspaces, manage members, read logs and activity, create or change management keys, or change credit settings such as auto top-up, billing details and refunds. Those need an administrator session in the dashboard. Such calls return 403 FORBIDDEN; a missing scope is named in details. Every operation in the API reference names its scope.

Fix 401 and 403

StatusGatewayManagement API
401authentication: the header is missing, the key expired, or it is invalid. Invalid covers typos and deleted, disabled or wrong-kind keys alike, so errors reveal nothing about existing keys.UNAUTHORIZED: missing, invalid or expired key, or an inference key.
403permission_denied: the key's rules exclude the model or tool, or the organization is suspended. Read issues and remedy_hint.FORBIDDEN: a scope is missing; details names it.

Fix the key or its rules before retrying; neither status heals on its own. Formats: error catalogs of the Gateway and the Management API. Retry rules: Errors and retries.

Next