> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.lumenia.net/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.lumenia.net/_mcp/server.

# Authentication

The LumenOne API authenticates requests with two pieces of context:

1. An **API key**, sent as a Bearer token in the `Authorization` header.
2. An **account id** (UUID), sent in the `X-Account-Id` header on routes that target a specific account.

## Getting an API key

> **Info**
>
> API keys can only be issued by a **LumenOne superadmin**. You cannot self-serve keys today.

To request a key:

1. Email your LumenOne contact (or `info@lumenia.net`) with your **company** name.
2. A LumenOne superadmin will provision the key and return it to you over a secure channel.
3. Store the key in a secrets manager — it grants company-wide access. There is no API to retrieve it after issuance, so if you lose it, contact a LumenOne superadmin to have a replacement issued.

## Sending the API key

Attach the key as a Bearer token on every request:

```bash
curl https://app.lumenia.net/api/v1/me \
  -H "Authorization: Bearer YOUR_API_KEY"
```

`GET /v1/me` verifies the key and returns the **partner** it belongs to:

```json
{
  "partner": { "name": "Acme Partner", "createdAt": "2026-06-15T05:24:00.000Z" }
}
```

A `403` response with `InvalidAPIKey` means the key is missing, malformed, or revoked.

## The `X-Account-Id` header

Most endpoints — anything that touches an organization, workspace, document, or tool — also require the `X-Account-Id` header. Its value must be the `id` of the account that owns those resources.

```bash
curl https://app.lumenia.net/api/v1/organizations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Account-Id: 550e8400-e29b-41d4-a716-446655440000"
```

Rules:

* The account must be one of **your customers** — an account your company owns. You can only act on accounts your key created.
* Org- and workspace-scoped routes additionally require the resource to belong to that account (that customer).
* Mismatches return `403` (the account is not one of yours) or `404` (the org/workspace is not under this account).

You can confirm an account is yours by passing its id to `GET /v1/me` — when valid, the account is echoed back alongside the partner:

```bash
curl https://app.lumenia.net/api/v1/me \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Account-Id: 550e8400-e29b-41d4-a716-446655440000"
```

```json
{
  "partner": { "name": "Acme Partner", "createdAt": "2026-06-15T05:24:00.000Z" },
  "account": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "LumenIA",
    "type": "ipaas",
    "createdAt": "2026-06-15T05:24:00.000Z"
  }
}
```

List the accounts your key can use with `GET /v1/accounts`.

The **account** endpoints themselves — `GET`/`POST /v1/accounts` and the `/v1/accounts/{accountId}` item routes — are partner-scoped and do **not** take `X-Account-Id`; an account is addressed directly by its `id`. The header only comes into play once you operate on the organizations, workspaces, documents, and tools *inside* an account.

## Key scope and rotation

* Keys are scoped to your company. They can read/write across all accounts and orgs your company owns — pair them with the appropriate `X-Account-Id` to narrow access.
* To rotate or revoke a key, contact a LumenOne superadmin. There is no self-service rotation endpoint yet.
* Treat keys as production secrets: do not embed in client-side code, public repos, or logs.