Skip to content
Docs

API Authentication

Two audiences: applications calling inference, and people or automation calling the management API.

The API Keys page, where keys are minted and revoked

API Keys → Create Key. Copy it then — it is shown once.

Terminal window
curl http://<host>:8001/v1/chat/completions \
-H "Authorization: Bearer $LIFEBOAT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"my-alias","messages":[{"role":"user","content":"hello"}]}'

Use a key rather than a user account: keys are scoped to inference and revocable individually, so a leaked key cannot change configuration and rotating one disturbs nothing else.

Keys also drive sticky-session affinity when that algorithm is selected — a digest of the key keeps one client on one backend so its cached prefix stays warm. The digest is what appears in the response header; the key never is.

When every server is busy, requests wait in Lifeboat’s queue. Waiting requests are served by key, not by arrival order:

  • Keys with the same priority take turns. After a request for one key is served, the next free slot goes to a different key that is waiting, round-robin. A key running a load test with hundreds of requests queued gets one turn per round, like every other key, so another key’s request waits for about one request to finish rather than for the whole backlog.
  • A higher priority is always served first. Every key starts at Standard (0). On API Keys, the Priority column sets a key to High (5) or Highest (10); the API accepts any value from 0 to 10 (PUT /api/api-keys/{id}/priority). Use it for a VIP key, sparingly: a busy high-priority key can make every lower-priority key wait.
  • A full queue sheds the heaviest key first. When the queue is at its limit, a new request from another key takes the place of the newest queued request of the key holding the most of the queue; that request gets 503 with X-Lifeboat-Reject-Reason: queue_full. A key that has filled the queue by itself has its own new requests refused. A higher-priority key’s queued request is never dropped for a lower-priority one.

A change of priority applies from the key’s next request. Requests without a key (when no keys are configured) are grouped by the X-Lifeboat-Session-Id header, else by client address. GET /api/lb/state reports queued requests per key (queue_by_client) and requests shed per key (queue_shed_by_client).

Fair sharing decides who gets the next free slot. It does not cap how many requests a key may have in flight at once, and it applies only while requests are queued: with the queue disabled (LIFEBOAT_LB_QUEUE_ENABLED=false) a busy server refuses requests with 503 instead.

An administrator can retrieve a stored key when it has genuinely been lost, and the reveal is written to the audit log. That is the trade: recoverable, but never quietly. If reveals appear in the audit log that nobody expected, treat it as an incident.

Add the new key, move clients to it, confirm traffic on the new key, then delete the old one. Nothing forces a rotation schedule; nothing prevents one either.

Authenticate as a user, with the role that covers the operation — see Users and roles. Viewer for reads, operator for server and model operations, admin for configuration, users and keys.

401 — missing or wrong bearer token. Check the header name and that the key was not truncated on copy.

402 license_required — the grace period has elapsed and no licence is active. This gates starting a server, not the console, so the activation page is always reachable. See Licensing.

Put TLS in front, or give Lifeboat a certificate and key. A bearer token over plaintext HTTP is a bearer token on the wire.