Authentication
Every /v1 request carries one API key as a bearer token. Keys belong to your account and share its credit balance.
Planned for the research API (milestone M5). Until it ships, the search and record endpoints return 404 not_found. Keys and GET /v1/key work now.
Sending the key
Authorization: Bearer lin_sk_live_...A missing or unknown key returns 401 with code invalid_api_key. A revoked key returns 401 with code api_key_revoked. Production accepts live keys (lin_sk_live_) only; a test key sent to production returns 401 with code invalid_api_key. Keys never go in a query string, because query strings end up in logs.
Key format
| Part | Meaning |
|---|---|
lin_sk_ | A Lineage secret key |
test_ or live_ | The live site issues live_ keys. Preview and local servers issue test_ keys, for trying the API |
the rest | 32 random letters and digits. Lineage stores only a SHA-256 hash and the first 16 characters, so a lost key cannot be shown again |
Creating, limiting and revoking keys
- Create keys on the keys page after you sign in with GitHub or Google. The full key is shown once, with a copy button.
- Give each agent its own key, with its own name, rate limit and credit limit, so one runaway agent cannot drain the account. The credit limit is stored now and enforced once searches spend credits.
- Revoke a key on the same page. It stops working on the next request.
Rate limits
Each key allows 60 requests per minute unless you set another limit when you create it. Every authenticated /v1 response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset headers. Past the limit, the API returns 429 rate_limited with retry_after in seconds and a Retry-After header.
Checking a key
GET /v1/key returns the key id, its visible prefix, its limits and the account balance in credits. Agents can call it before a long run to decide how deep to search.
{
"id": "key_...",
"prefix": "lin_sk_live_4f2a",
"name": "research agent",
"env": "live",
"limits": { "requests_per_minute": 60, "credits": 2000 },
"balance_credits": 940,
"created_at": "2026-11-01T18:00:00.000Z",
"last_used_at": "2026-11-01T18:05:00.000Z"
}limits.credits is null when the key has no credit limit. The numbers above are an example, not a real account.