# Look up an API key

Read-only search, with the same tenant/type/owner/expiration filters as the directory. Never send plaintext keys in this body or any URL.

`POST https://tokenlane.de/api/keys/lookup`

## Authorizations

[
  [
    {
      "name": "Authorization",
      "description": "Organization management key: `Authorization: Bearer sk-tl-v1-…`. Existing `sk-eu-` keys remain valid. Required scopes are listed in `x-scopes`; gateway inference keys cannot authorize management operations.",
      "type": "http bearer",
      "location": "",
      "scopes": []
    }
  ]
]

Values starting with YOUR_ are placeholders. Replace them with appropriate values before sending.

## curl

```curl
curl --request POST \
  --url 'https://tokenlane.de/api/keys/lookup' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Origin: https://tokenlane.de' \
  --header 'Content-Type: application/json' \
  --data '{
  "workspaceId": "wsp_01k7tm3w8vfz6b2r4m9q5xyz7c",
  "keyHash": "YOUR_KEYHASH"
}'
```

## node

```node
const response = await fetch("https://tokenlane.de/api/keys/lookup", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.TOKENLANE_API_KEY,
    "Origin": "https://tokenlane.de",
    "Content-Type": "application/json",
  },
  body: `{
  "workspaceId": "wsp_01k7tm3w8vfz6b2r4m9q5xyz7c",
  "keyHash": "YOUR_KEYHASH"
}`,
});
console.log(await response.text());
```

## python

```python
import os
import urllib.request

body = (r'''{
  "workspaceId": "wsp_01k7tm3w8vfz6b2r4m9q5xyz7c",
  "keyHash": "YOUR_KEYHASH"
}''').encode("utf-8")

request = urllib.request.Request(
    "https://tokenlane.de/api/keys/lookup",
    method="POST",
    headers={
        "Authorization": "Bearer " + os.environ["TOKENLANE_API_KEY"],
        "Origin": "https://tokenlane.de",
        "Content-Type": "application/json",
    },
    data=body,
)

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/lookup", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.TOKENLANE_API_KEY,
    "Origin": "https://tokenlane.de",
    "Content-Type": "application/json",
  },
  body: `{
  "workspaceId": "wsp_01k7tm3w8vfz6b2r4m9q5xyz7c",
  "keyHash": "YOUR_KEYHASH"
}`,
});
console.log(await response.text());
```

## Body: application/json

```json
{
  "workspaceId": "wsp_01k7tm3w8vfz6b2r4m9q5xyz7c",
  "keyHash": "YOUR_KEYHASH"
}
```

### s17: object

{"additionalProperties":"false"}

- q (optional): s0

### s0: string

Search in name and display prefix. Never send full keys; use the SHA-256 lookup.

{"maxLength":"100"}

- owner (optional): s77

### s77: anyOf

{}

anyOf: s51

### s51: string

"me", "workspace"

{}

anyOf: s52

### s52: string

Filter by an organization member

{}

```json
"mem_01k7tm3w8vfz6b2r4m9q5xyz7c"
```

- expiration (optional): s2

### s2: string

Expiry facet on the database clock: `never` has no `expires_at`, `expired` has reached it (the instant itself counts, as in the gateway), `scheduled` lies in the future

"never", "expired", "scheduled"

{}

- isManagement (optional): s3

### s3: string

Restrict key type; omitted preserves the combined legacy list

"true", "false"

{}

- workspaceId (optional): s4

### s4: string

Only keys of this workspace

{}

```json
"wsp_01k7tm3w8vfz6b2r4m9q5xyz7c"
```

- status (optional): s5

### s5: string

`active` keys are enabled and not expired, so the gateway accepts them; `disabled` keys are disabled regardless of expiry. Without a status, enabled expired keys stay listed; combine with `expiration=expired` to find them.

"active", "disabled"

{}

- sort (optional): s6

### s6: string

"name", "createdAt"

{"default":"\"createdAt\""}

- order (optional): s7

### s7: string

"asc", "desc"

{"default":"\"desc\""}

- page (optional): s8

### s8: integer

{"minimum":"1","maximum":"1000000","default":"1"}

- pageSize (optional): s9

### s9: integer

{"default":"20"}

- keyHash (required): s78

### s78: string

SHA-256 computed locally; never send the plaintext key

{"pattern":"\"^[a-f0-9]{64}$\""}

## Response 200: application/json

Request successful

```json
{
  "items": [
    {
      "id": "key_01k7tm3w8vfz6b2r4m9q5xyz7c",
      "name": "Production backend",
      "keyPrefix": "sk-tl-v1-4fKq",
      "workspace": {
        "id": "wsp_01k7tm3w8vfz6b2r4m9q5xyz7c",
        "name": "Default"
      },
      "isManagement": false,
      "owner": {
        "kind": "workspace"
      },
      "usage": {
        "currency": "EUR",
        "lastUsedAt": "YOUR_LASTUSEDAT",
        "totalPicoEur": "YOUR_TOTALPICOEUR",
        "periodPicoEur": "YOUR_PERIODPICOEUR",
        "periodStartsAt": "YOUR_PERIODSTARTSAT",
        "asOf": "YOUR_ASOF"
      },
      "disabled": false,
      "policy": {
        "allowed_models": [
          "deepseek/deepseek-v4.1-flash",
          "mistralai/*"
        ],
        "denied_models": [
          "openai/*"
        ],
        "allowed_countries": [
          "DE",
          "FR"
        ],
        "expires_at": "2026-12-31T23:59:59Z",
        "limit": "25"
      },
      "createdAt": "YOUR_CREATEDAT",
      "updatedAt": "YOUR_UPDATEDAT"
    }
  ],
  "total": 0,
  "page": 0,
  "pageSize": 0
}
```

### s10: object

{}

- items (required): s53

### s53: array

{}

### s15: object

{}

- id (required): s66

### s66: string

Key identity (never the key itself)

{}

```json
"key_01k7tm3w8vfz6b2r4m9q5xyz7c"
```

- name (required): s67

### s67: string

{}

```json
"Production backend"
```

- keyPrefix (required): s68

### s68: string

Start of the key, to recognise it

{}

```json
"sk-tl-v1-4fKq"
```

- workspace (required): s69

### s69: object

Workspace the key belongs to

{}

- id (required): s100

### s100: string

{}

```json
"wsp_01k7tm3w8vfz6b2r4m9q5xyz7c"
```

- name (required): s103

### s103: string

{}

```json
"Default"
```

- isManagement (required): s70

### s70: boolean

Manages keys of the organization, cannot call models

{}

- owner (required): s71

### s71: oneOf

Organization-scoped attribution, selected at creation

{}

oneOf: s155

### s155: object

{}

- kind (required): s170

### s170: string

"workspace"

{}

oneOf: s156

### s156: object

{}

- kind (required): s172

### s172: string

"member"

{}

- memberId (required): s35

### s35: string

{}

- userId (required): s35

- name (required): s35

- email (required): s35

- usage (required): s43

### s43: object

{}

- currency (required): s81

### s81: string

"EUR"

{}

- lastUsedAt (required): s138

### s138: string | null

Latest generation creation time, never a management write timestamp

date-time

{}

- totalPicoEur (required): s139

### s139: string | null

All recorded key costs in integer pico-EUR; null if unavailable

{"pattern":"\"^\\\\d+$\""}

- periodPicoEur (required): s140

### s140: string | null

Recorded costs in the current UTC policy window; lifetime without a reset

{"pattern":"\"^\\\\d+$\""}

- periodStartsAt (required): s86

### s86: string | null

date-time

{}

- asOf (required): s141

### s141: string | null

Accounting projection time; null in mutation responses or when not applicable

date-time

{}

- disabled (required): s72

### s72: boolean

Disabled keys are rejected by the gateway

{}

- policy (required): s40

### s40: object

Rules for a key, in the shape the gateway reads (gw_core::KeyPolicy). Unknown fields are rejected. The rules that apply to a request are the intersection of the organization, workspace and key policy: a level can only restrict.

{"additionalProperties":"false"}

- bridges (optional): s106

### s106: object

Automatic conversions per bridge (`file-parser`: PDF to text). Inner levels can only restrict: a stricter mode or a lower cost limit.

{"additionalProperties":"false"}

- file-parser (optional): s41

### s41: object

Restrictions for one bridge at one level.

{"additionalProperties":"false"}

- mode (optional): s128

### s128: string

`auto` converts only when the request would otherwise fail, `opt_in` only when the request enables the plugin, `off` never. Left out: `auto`.

"off", "opt_in", "auto"

{}

- max_auto_cost (optional): s129

### s129: string | null

Highest automatic reservation in EUR as a decimal string; null or left out inherits the configured ceiling. Explicit plugins are not capped here.

{}

```json
"0.05"
```

- locked (optional): s130

### s130: boolean

Requests cannot opt out of an effective automatic bridge. Inner levels can still restrict the bridge further, as always; they can never loosen it.

{}

- byok (optional): s107

### s107: boolean | null

Funding: true requires BYOK; false prohibits BYOK; null inherits.

{}

- allowed_models (optional): s108

### s108: array

Model IDs or patterns (`*` matches anything) the key may use. Left out: every model.

{"minItems":"1","maxItems":"200"}

```json
[
  "deepseek/deepseek-v4.1-flash",
  "mistralai/*"
]
```

### s163: string

{"minLength":"1","maxLength":"256"}

```json
"mistralai/*"
```

- denied_models (optional): s109

### s109: array

Model IDs or patterns that are refused although `allowed_models` matches them. A refusal of any level always wins.

{"maxItems":"200"}

```json
[
  "openai/*"
]
```

- allowed_providers (optional): s110

### s110: array

Providers that may serve requests, named like `provider.only` (provider ID, or `provider/variant` for one tariff variant). Left out: every provider.

{"minItems":"1","maxItems":"200"}

### s164: string

{"minLength":"1","maxLength":"128"}

```json
"mistral"
```

- denied_providers (optional): s111

### s111: array

Providers that must not serve requests, named like `provider.ignore`.

{"maxItems":"200"}

- allowed_countries (optional): s112

### s112: array

Countries in which processing is permitted (ISO 3166-1 alpha-2, uppercase). A route qualifies only if it states its processing countries and all of them are listed.

{"minItems":"1","maxItems":"249"}

```json
[
  "DE",
  "FR"
]
```

### s165: string

{"pattern":"\"^[A-Z]{2}$\""}

```json
"DE"
```

- min_compliance (optional): s113

### s113: string

Weakest jurisdiction guarantee a route may have, in ascending order: `global` (unrestricted), `eu_data_residency`, `eu_operated` or `sovereign_eu`.

"global", "eu_data_residency", "eu_operated", "sovereign_eu"

{}

- require_zdr (optional): s114

### s114: boolean

Only routes with zero retention of prompt and completion contents.

{}

- deny_training (optional): s115

### s115: boolean

Exclude routes whose provider may train on customer data (also when unknown).

{}

- max_price (optional): s42

### s42: object

Highest accepted route prices in EUR as decimal strings; a request cannot raise them.

{"additionalProperties":"false"}

- prompt (optional): s131

### s131: string

EUR per million input tokens.

{}

```json
"25"
```

- completion (optional): s132

### s132: string

EUR per million output tokens.

{}

```json
"25"
```

- request (optional): s133

### s133: string

EUR per upstream request.

{}

```json
"25"
```

- image (optional): s134

### s134: string

EUR per input image.

{}

```json
"25"
```

- audio (optional): s135

### s135: string

EUR per input audio unit declared by the route.

{}

```json
"25"
```

- page (optional): s136

### s136: string

EUR per OCR page.

{}

```json
"25"
```

- character (optional): s137

### s137: string

EUR per PII input character.

{}

```json
"25"
```

- forbid_capture (optional): s116

### s116: boolean

Prompts and completions must not be stored, whatever a key's `capture` says.

{}

- default_sort (optional): s117

### s117: string

Default for `provider.sort` when a request names none.

"price", "throughput", "latency"

{}

- default_allow_fallbacks (optional): s118

### s118: boolean

Default for `provider.allow_fallbacks` when a request names none.

{}

- locked (optional): s119

### s119: array

Routing defaults of this policy that requests and inner levels cannot override. A setting listed here needs its default in the same policy.

{}

### s166: string

"sort", "allow_fallbacks"

{}

- rate_limits (optional): s120

### s120: object

{"additionalProperties":"false"}

- rpm (optional): s167

### s167: integer | null

{"minimum":"1","maximum":"4294967295"}

- tpm (optional): s167

- max_parallel_requests (optional): s167

- pii_redact (optional): s121

### s121: array

Operator-provisioned enforced redaction. Console reads and edits retain existing rules; changing these rules requires operator validation of the detector and provider configuration.

{"maxItems":"16"}

### s168: object

{"additionalProperties":"false"}

- when (optional): s184

### s184: object

{"additionalProperties":"false"}

- below_compliance (optional): s191

### s191: string | null

Weakest jurisdiction guarantee a route may have, in ascending order: `global` (unrestricted), `eu_data_residency`, `eu_operated` or `sovereign_eu`.

"global", "eu_data_residency", "eu_operated", "sovereign_eu", null

{}

- providers_except (optional): s192

### s192: array | null

{"maxItems":"128"}

- models (optional): s193

### s193: array | null

{"minItems":"1","maxItems":"128"}

- entities (optional): s185

### s185: array

{"minItems":"1"}

### s194: string

"person", "address", "email", "phone", "iban", "identifier", "date_of_birth", "organization"

{}

- threshold (optional): s186

### s186: number

{"minimum":"0","maximum":"1"}

- restore (optional): s89

### s89: boolean

{}

- expires_at (optional): s122

### s122: string

From this instant on the key is rejected (RFC 3339).

date-time

{}

```json
"2026-12-31T23:59:59Z"
```

- allow_attribution_export (optional): s123

### s123: boolean | null

Caller attribution export requires global operator enablement and the key's explicit true opt-in. False at the organization, workspace or key vetoes export; absent or null inherits without opting a key in.

{}

- capture (optional): s124

### s124: boolean

Whether prompts and completions of this key are stored for later retrieval.

{}

- limit (optional): s125

### s125: string

Spending limit in EUR as a decimal string.

{}

```json
"25"
```

- limit_reset (optional): s126

### s126: string

UTC window after which spending against `limit` starts from zero (weeks start on Monday).

"daily", "weekly", "monthly"

{}

- server_tools (optional): s127

### s127: array

Server tools the key may use; they cost extra and send parts of the request to third parties.

{}

### s169: string

"web_search"

{}

- createdAt (required): s73

### s73: string

Creation timestamp

date-time

{}

- updatedAt (required): s74

### s74: string

Last update timestamp

date-time

{}

- total (required): s54

### s54: integer

Number of keys matching the filters

{}

- page (required): s55

### s55: integer

{}

- pageSize (required): s55

## Response 400: application/json

Bad request (validation error, invalid input)

```json
{
  "status": 400,
  "code": "VALIDATION_ERROR",
  "message": "Request validation failed"
}
```

### s11: object

{}

- requestId (optional): s56

### s56: string

Server correlation ID for an internal error. Also returned in X-Request-Id.

uuid

{}

- status (required): s57

### s57: number

HTTP status code

{}

```json
400
```

- code (required): s58

### s58: string

Error code

{}

```json
"VALIDATION_ERROR"
```

- message (required): s59

### s59: string

Error message

{}

```json
"Request validation failed"
```

- remedy_hint (optional): s60

### s60: string

A safe, actionable remedy from the error catalog.

{}

- details (optional): s61

### s61: array

Detailed validation errors

{}

### s154: object

{}

- path (required): s179

### s179: string

Field path

{}

```json
"title"
```

- message (required): s180

### s180: string

Field error message

{}

```json
"Required"
```

## Response 401: application/json

Authentication required (missing or invalid credentials)

```json
{
  "status": 400,
  "code": "VALIDATION_ERROR",
  "message": "Request validation failed"
}
```

## Response 403: application/json

Insufficient scope (authenticated but not authorized)

```json
{
  "status": 400,
  "code": "VALIDATION_ERROR",
  "message": "Request validation failed"
}
```

## Response 404: application/json

Resource not found

```json
{
  "status": 400,
  "code": "VALIDATION_ERROR",
  "message": "Request validation failed"
}
```

## Response 409: application/json

Read and accept the currently published terms before continuing with this session

```json
{
  "status": 400,
  "code": "VALIDATION_ERROR",
  "message": "Request validation failed"
}
```

## Response 500: application/json

Internal server error

```json
{
  "status": 400,
  "code": "VALIDATION_ERROR",
  "message": "Request validation failed"
}
```

## Response 503: application/json

Configured upstream timed out, failed or returned an invalid response

```json
{
  "status": 400,
  "code": "VALIDATION_ERROR",
  "message": "Request validation failed"
}
```
