Get started

Authentication

API keys, account context, and how to obtain credentials.

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

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 [email protected]) 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:

$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:

1{
2  "partner": { "name": "Acme Partner", "createdAt": "2026-06-15T05:24:00.000Z" }
3}

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.

$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:

$curl https://app.lumenia.net/api/v1/me \
>  -H "Authorization: Bearer YOUR_API_KEY" \
>  -H "X-Account-Id: 550e8400-e29b-41d4-a716-446655440000"
1{
2  "partner": { "name": "Acme Partner", "createdAt": "2026-06-15T05:24:00.000Z" },
3  "account": {
4    "id": "550e8400-e29b-41d4-a716-446655440000",
5    "name": "LumenIA",
6    "type": "ipaas",
7    "createdAt": "2026-06-15T05:24:00.000Z"
8  }
9}

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.