# 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](https://tokenlane.de/keys), by owners, admins and developers. | [Management keys](https://tokenlane.de/settings/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](https://tokenlane.de/docs/guides/organizations-and-workspaces.md?lang=en).

| 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:

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
curl --request GET \
  --url 'https://tokenlane.de/api/keys' \
  --header 'Authorization: Bearer YOUR_MANAGEMENT_KEY'
```

### node

```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

```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

```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](https://tokenlane.de/docs/gateway/errors.md?lang=en) and the [Management API](https://tokenlane.de/docs/management/errors.md?lang=en). Retry rules: [Errors and retries](https://tokenlane.de/docs/guides/errors-and-retries.md?lang=en).

## Next

- [Quickstart](https://tokenlane.de/docs/guides/quickstart.md?lang=en): the first request
- [Organizations and workspaces](https://tokenlane.de/docs/guides/organizations-and-workspaces.md?lang=en): who creates keys, where credit lives
- [Move from OpenRouter](https://tokenlane.de/docs/guides/openrouter-migration.md?lang=en)