Skip to main content

API Authentication

Calls to https://lium.io/api/... that touch your account send an API key in the X-API-Key header. To create keys see API Keys.

The header​

curl https://lium.io/api/pods -H "X-API-Key: $LIUM_API_KEY"
  • Send the key as copied from Access → API Keys. No Bearer prefix.
  • Everything the key rents is billed to its account.
  • A default key holds read, rent and manage. Payments need a separate billing key. See scopes.
  • Some account operations need a signed-in session, not a key. See API → Authentication.

Where the key comes from​

The CLI and the SDK read the same key. The environment variable wins:

OrderSourceSet by
1LIUM_API_KEY environment variableexport LIUM_API_KEY=...
2~/.lium/config.ini, [api] section, api_keylium init, lium signup, lium config set api.api_key

lium config get api.api_key shows the start and end of the key the CLI uses. In Python you can also pass it directly: Lium(Config(api_key="...")).

Verify a key before you rent​

GET /executors and GET /templates work without a key, so use an account call:

# REST
curl -sS https://lium.io/api/users/me -H "X-API-Key: $LIUM_API_KEY"

# CLI
lium balance --json
from lium.sdk import Lium, LiumAuthError

try:
    balance = Lium().balance()          # GET /users/me
except LiumAuthError as exc:
    raise SystemExit(f"API key rejected: {exc}")

Renting also needs a balance above about 15 minutes of the node's hourly price plus 15 minutes of each pod you already have running.

Error responses​

Errors use one JSON envelope. Read error.code, show error.hint, and quote error.request_id when you ask for help:

{
  "success": false,
  "error": {
    "code": "unauthorized",
    "message": "API key not found",
    "hint": "Send a valid key in X-API-Key (lium.io/api-keys) or sign in again; `lium config get api.api_key` shows the key the CLI uses.",
    "request_id": "2510eff403c14e4e9ff4bf744bb05df6"
  },
  "message": "API key not found",
  "status_code": 401,
  "request_id": "2510eff403c14e4e9ff4bf744bb05df6"
}
StatusMeaningWhat to do
401Key missing or unknownSend the header; check the key on Access → API Keys
403Key is valid but the account may not do this, often a low balanceTop up with lium topup
402GET /pods by a key that can rent, on an account with no balance and no pods (a read-only key gets [])Top up with lium topup
429Too many requestsBack off and retry

The CLI exits 3 on API errors, 6 on permission errors and 2 when no key is set. The SDK raises LiumAuthError (401), LiumPermissionError (403), LiumNotFoundError (404) and LiumRateLimitError (429), all subclasses of LiumError.

Keep the key safe​

  • Keep the key out of pods, images and templates. Pass it as an environment variable. See Pod security.
  • Use one key per integration, so you can revoke it alone.
  • Log only the key's prefix.