---
sidebar_position: 9
tags: [api, agents]
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lium.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API Keys

Most renters never need this page. Use it when:

- You want to drive Lium from the **CLI** (`lium ...`).
- You want an **AI agent** (Claude, Cursor, your own) to deploy and manage pods on your behalf via the API or [MCP server](/developers/mcp).
- You're integrating Lium into a CI pipeline, a Slack bot, or your own tool.

If you're just here to rent a GPU and SSH in, the dashboard at [lium.io](https://lium.io) is the friendlier path — see [Quickstart](./quickstart).

## What an API key does

An API key authenticates HTTP requests to `https://lium.io/api/...` as **you**. Anyone with the key can:

- Deploy pods, attach volumes, start backups — and **be billed to your account**.
- Read your pod list, backup history, and account balance.
- Delete things. There is no read-only or otherwise narrower key yet — [scopes](#scopes) are not released.

Treat the key like a password. Never paste it into a public repo, an issue tracker, a screenshot, or a non-CVM pod.

## Generate a key

1. Sidebar → **Access** (key icon).
2. Click the **API Keys** tab.
3. **ADD NEW +**, give the key a **Name** (something like `cli-laptop`, `ci-deploy-bot`, `claude-agent`), **ADD**.
4. The full key shows in a copy-to-clipboard chip. The table keeps the full key: the masked **Key** column's copy button copies it again any time.

![Access page → API Keys tab](./assets/api-keys-list.png)

The list view shows each key's **Name**, masked **Key** prefix, **Active** flag, **Last used**, **Expires at**, and **Date created**.

## Use the key

Pass the key in the `X-API-Key` header on every request:

```bash
export LIUM_API_KEY=sk_yjujqGP...full-key

curl https://lium.io/api/pods \
  -H "X-API-Key: $LIUM_API_KEY"
```

For the CLI:

```bash
pip install lium.io                   # or: curl https://lium.io/install.sh | sh
lium init                             # guided login (or set LIUM_API_KEY in your env)
lium ps                               # list your pods
```

For the [SDK](/developers/sdk) and [MCP server](/developers/mcp), set `LIUM_API_KEY` in the environment. The environment variable takes precedence over `~/.lium/config.ini`; [API Authentication](/developers/authentication) lists every source, the order they are read in, and how to check which key is in use.

## Scopes

:::note Coming in lium-platform#208
Nothing in this section is released: today every key can do everything the account can. Read / rent / manage scopes, `scopes` on `POST /keys`, `created_by_api_key_id` on `GET /pods` and the 403s that name a missing scope are lium-platform#208.

A key holds any subset of three scopes. Whatever its scopes, a key can always see, reboot, edit and delete **the pods it rented itself**.

| Scope | Adds | Without it |
|---|---|---|
| `read` | see every pod of the account | the key sees only the pods it rented (`GET /pods` lists just those; another pod's detail is a 404 — its event log, `GET /pods/{id}/events`, is not fenced) |
| `rent` | create pods; like `manage`, it also unlocks the account-wide writes a `read`-only key is refused (SSH keys, templates, volumes, payments) | `POST /executors/{id}/rent` is a 403 |
| `manage` | reboot / edit / delete / restore / add SSH keys to pods it did **not** rent | those calls are a 403 naming the missing scope |

Scopes fence off pods, not the account: account-wide writes (SSH keys, templates, volumes, payments) go through with `rent` or `manage`; only a `read`-only key is refused there, with a 403 that names the key and the call.

Recipes:

- **Sandboxed agent** — `["rent"]`. It can rent, work on and tear down its own pods and cannot list, open or change anyone else's (their event log, like the account log, stays readable). It can still write account-wide things (SSH keys, templates, volumes) — scopes fence off pods, not the account.
- **Monitor** — `["read"]`. Dashboards and cost scripts; changes nothing.
- **Operator / CI that cleans up after others** — the default (all three).

Scopes are chosen when the key is created and cannot be widened later — create a new key instead. Every key created before scopes existed, and every key created without choosing, holds all three. Key creation is `POST /keys` from a logged-in session (a key can never mint keys) with the scopes in the body:

```json
{"name": "claude-agent", "scopes": ["rent"]}
```

Each pod records the key that rented it (`created_by_api_key_id` in `GET /pods`), and the [account event log](#who-did-what-on-the-account) names the key behind every action. Browser sessions are never scoped.
:::

## Quick "API Key" button (top-left)

The **API Key** button at the very top of the sidebar (under your balance) **copies your most recent active key to the clipboard** and shows a toast. Handy for quick re-pastes; not a substitute for managing keys on the Access page.

## Rotate, deactivate, delete

On the **Access → API Keys** row:

- ✏️ **Edit** — rename or set an expiry date.
- 🗑️ **Delete** — revokes the key immediately. Anything using it (CLI session, running agent) will start getting 401s.

There's no separate "deactivate but keep" toggle yet — delete and recreate when you need to rotate.

## What this unlocks for AI agents

The whole Renters surface (pods, templates, volumes, backups, restores, scheduled termination) is exposed via the same REST API and via the [MCP server](/developers/mcp). With one API key, an agent can:

- Watch the marketplace and deploy a cheap pod when an A100 drops below your price ceiling.
- Spin up a fresh pod for each job, run training, take a final backup, terminate.
- Pull a backup down for inspection in your laptop, then fan out restores into many pods.
- Manage templates: keep your team's images, tags, and entrypoints in sync from CI.

Schemas live in the [API page](/developers/api). The Renters pages above each have a "For agents and automation" block at the bottom showing the curl/CLI equivalents of every UI flow.

## Who did what on the account

Every pod event on the account — created, rebooted, deleted, failed — is recorded and readable with the account's browser session token:

```bash
curl -s https://lium.io/api/users/me/events -H "Authorization: Bearer $JWT" \
  | jq -r '.[] | "\(.created_at)  \(.event_type)  \(.event)"'
```

Each entry carries `event_type`, `created_at` and the `event` payload (pod name, executor, the error where there is one). Two limits today: the endpoint takes the session JWT only (not an API key), and an event does not yet say which key or session caused it — per-key attribution (`actor`) and the `since` / `pod_id` / `api_key_id` filters are in lium-platform#208 (which folded #69), not released. Until then, one key per agent still pays off through the pod names: name pods after the job (`--name ci-trainer-42`) and the event log tells you who did what by name.

## Key hygiene

- One key per integration. If your laptop's key leaks, you only revoke that one — and, once lium-platform#208 ships, the event log tells the integrations apart.
- Set an **Expires at** for short-lived agents (CI runners, hackathon scripts).
- Don't bake keys into Docker images or templates. Set them as env vars at runtime, or use the agent itself to deploy with a short-lived key.
- Never put a key in a non-CVM pod's filesystem — see [Pod security](./security).