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

# API Keys

> Authenticate the CLI, scripts, and integrations

API keys are long-lived bearer tokens that authenticate requests to Lyceum Cloud. They're prefixed `lk_` and pass in the `Authorization` header on every request:

```bash theme={null}
curl https://api.lyceum.technology/api/v2/external/billing/credits \
  -H "Authorization: Bearer lk_your_api_key"
```

Every endpoint in the [API Reference](/api-reference/introduction) accepts the same header.

## Keys belong to an organization

Every API key is scoped to a single [organization](/docs/account/organizations). The key authenticates the request **and** pins it to that org, there's no need to send an extra `X-Org-Slug` header.

The credits, runs, VMs, and deployments associated with the request are all billed and accessed through the key's org.

If you belong to several orgs, create a separate key in each one for the scripts that act on its behalf.

## API keys vs JWT tokens

The platform supports two token types:

| Token                  | Lifetime                             | When to use                                                |
| ---------------------- | ------------------------------------ | ---------------------------------------------------------- |
| **API key** (`lk_...`) | Long-lived, until revoked or expired | CLI in CI, scripts, integrations, anything non-interactive |
| **JWT**                | Short-lived, refreshable             | Interactive dashboard sessions, API playground, testing    |

JWT users can act on any org they're a member of by sending `X-Org-Slug: <slug>`; with an API key, the org is fixed by the key itself.

## Lifecycle

API keys can be:

* **Created** with a name and an optional expiration date. Creation requires the `owner` or `admin` role in the org.
* **Regenerated** to issue a fresh secret while keeping the key's name, org, and expiration. The previous secret stops working immediately, so rotate a key without touching the scripts that reference it by name.
* **Revoked** at any time, effective immediately. The row is kept for the audit trail.

The full key value is returned **exactly once**, in the response to the create or regenerate request. After that, only the prefix (first 8 characters) is visible. If you lose a key, regenerate it or revoke it and create a new one.

Creating, regenerating, and revoking all require the `owner` or `admin` role in the org.

<Warning>
  API keys grant the same access as members of the org they're scoped to. Store them in a password manager or secret store, and never commit them to source control.
</Warning>

## Dashboard

Open **API Keys** in the dashboard. The page lists every key across every org where you're an owner or admin, with a filter to narrow by org. Create a new key with the **New API Key** button; the dialog defaults to the active org but you can pick any org you can manage. Each key row has a **regenerate** button (the circular-arrows icon) to rotate its secret in place, and a **revoke** button to disable it. As with creation, the new value from a regenerate is shown only once.

## CLI

```bash theme={null}
# List keys in the active org
lyceum org keys list

# Create a key in the active org
lyceum org keys create ci-pipeline

# Create a key in a different org without switching active
lyceum org keys create deploy-prod --org production --expires-at 2027-01-01T00:00:00Z

# Revoke
lyceum org keys revoke <key_id>
```

## REST API

| Method   | Endpoint                                    | Purpose                                                |
| -------- | ------------------------------------------- | ------------------------------------------------------ |
| `GET`    | `/orgs/{slug}/api-keys`                     | List the org's keys (metadata only)                    |
| `POST`   | `/orgs/{slug}/api-keys`                     | Create a key, returns the plaintext value once         |
| `POST`   | `/orgs/{slug}/api-keys/{key_id}/regenerate` | Regenerate a key, returns the new plaintext value once |
| `DELETE` | `/orgs/{slug}/api-keys/{key_id}`            | Revoke a key                                           |

They all require the `owner` or `admin` role in the org.

```bash theme={null}
# Create a key
curl -X POST https://api.lyceum.technology/api/v2/external/orgs/acme/api-keys \
  -H "Authorization: Bearer <your-jwt-or-existing-key>" \
  -H "Content-Type: application/json" \
  -d '{"name": "ci-pipeline", "expires_at": "2027-01-01T00:00:00Z"}'
```

The response contains `plaintext_key`, store it immediately.