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 UUID, sent in the X-Account-Id header on routes that target a specific account.

Getting an API key

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 and cannot be retrieved again after issuance.

Sending the API key

Attach the key as a Bearer token on every request:

$
curl https://your-lumenone-host/api/v1/auth \
>
  -H "Authorization: Bearer YOUR_API_KEY"

You can verify a key is valid by calling GET /v1/auth:

1
{ "authenticated": true }

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 number — also require the X-Account-Id header:

$
curl https://your-lumenone-host/api/v1/org/$ORG_SLUG/documents \
>
  -H "Authorization: Bearer YOUR_API_KEY" \
>
  -H "X-Account-Id: 11111111-2222-3333-4444-555555555555"

Rules:

• The account must belong to your company.
• Org-scoped routes additionally require the org to belong to that account.
• Mismatches return 403 (wrong company) or 404 (org not under this account).

GET /v1/orgs accepts the header optionally — omit it to list every org under your company; include it to narrow to a single 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.