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 key | Management key | |
|---|---|---|
| Purpose | Calls models. | Manages the organization's inference keys and reads its credit. |
| Endpoint | The gateway, /v1/... | The Management API on the dashboard host, /api/... |
| Created in | API Keys, by owners, admins and developers. | Management keys, by owners and admins. |
| Belongs to | One workspace. | The organization. |
| Scopes | none | keys:read, keys:write, workspaces:read, credits:read |
| Variable | TOKENLANE_API_KEY | TOKENLANE_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.
| Rule | Effect | Failure |
|---|---|---|
expires_at | Rejects the key from that moment; running requests and streams finish. | 401 authentication |
limit, limit_reset | EUR budget, optionally reset daily, weekly (from Monday) or monthly in UTC. | 402 insufficient_credits when the rest cannot cover a request |
allowed_models | Model IDs or * patterns. Fallbacks outside the list are skipped. | 403 permission_denied; remedy_hint names the allowed models |
server_tools | web_search allows the web plugin. | 403 permission_denied |
capture | Stores this key's prompts and answers for later retrieval. | none |
Replace a key
There is no rotate button. Instead:
- Create the new key in the same workspace with the same rules.
- Deploy it, and watch Last Used on the old one.
- Disable the old key: it is rejected within seconds and can be enabled again.
- 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
| Status | Gateway | Management API |
|---|---|---|
| 401 | authentication: 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. |
| 403 | permission_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
- Quickstart: the first request
- Organizations and workspaces: who creates keys, where credit lives
- Move from OpenRouter