> 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.

# Accounts

An **account** is one of **your customers**. Your company (the **partner** that owns the API key) can have many accounts — typically one per customer — and each account holds that customer's organizations.

```
Partner  (your company — your API key)
└── Account  (one of your customers)
    └── Organization
        └── Workspace
```

An account is the level at which you separate one customer from another. Everything below it — organizations, workspaces, documents, tools — belongs to exactly one account, so a customer's data is isolated from every other customer's.

## You decide how customers are structured

A single customer (account) can have **as many organizations as you give them** — for example one per brand, region, or department. LumenOne does not impose a limit or a structure: we provide the API endpoints, and how you map your customers onto accounts and organizations — and any limits you want to enforce — is entirely your product decision.

> **Info**
>
> Think of an account as *"this customer"* and its organizations as *"the tenants that customer runs."* You are free to create one account per customer and one or many organizations under it, whatever fits your product.

## The account id is X-Account-Id

Every account has an `id` (a UUID). That id is exactly the value you put in the **`X-Account-Id`** header to scope org- and workspace-level calls to a customer.

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

The same API key serves all your accounts; the header selects which customer a request applies to. An `X-Account-Id` that is not one of your accounts is rejected with `403`. See [Authentication](/documentation/get-started/authentication).

## What an account looks like

`GET /v1/accounts/{accountId}` returns:

| Field                  | Meaning                                                                 |
| ---------------------- | ----------------------------------------------------------------------- |
| `id`                   | The account id (UUID) — use it as `X-Account-Id`.                       |
| `name`                 | Human-readable customer name.                                           |
| `type`                 | The account type. Accounts created through this API are always `ipaas`. |
| `createdAt`            | When the account was created.                                           |
| `counts.organizations` | Number of active organizations under the account.                       |

The organizations themselves are listed by `GET /v1/organizations` (scoped by `X-Account-Id`) — the detail carries a count, not the list.

## Lifecycle

Account list and create are **partner-scoped**: they act on your company directly and do **not** take an `X-Account-Id` header.

| Action | Endpoint                          | Notes                                                                     |
| ------ | --------------------------------- | ------------------------------------------------------------------------- |
| List   | `GET /v1/accounts`                | All accounts under your company.                                          |
| Create | `POST /v1/accounts`               | Body needs a `name`. The type is always `ipaas` for API-created accounts. |
| Read   | `GET /v1/accounts/{accountId}`    | The detail above.                                                         |
| Rename | `PATCH /v1/accounts/{accountId}`  | Only the `name` can be updated.                                           |
| Delete | `DELETE /v1/accounts/{accountId}` | Removes the account and everything under it. This cannot be undone.       |

> **Warning**
>
> Deleting an account is destructive and irreversible — its organizations, workspaces, documents, tools, and integrations are all torn down. Delete with care.