How does authentication work for the Luminous External API, and what headers are required?

Overview

Every call to the Luminous External API must be authenticated. Luminous supports two authentication methods: the classic API Token (used by almost all integrations) and an OAuth 2.0 access token (available on accounts where OAuth has been enabled). Both methods use the same HTTP header format.

Required Request Headers

Include all three headers on every request:

Header	Value
`Authorization`	`Bearer <your-api-token>`

We also recommend Accept: application/json, and Content-Type: application/json on requests with a body.

If the Authorization header is missing or the token isn't recognized, Luminous returns 401 Unauthorized.

Method 1 — API Token (Standard)

To create or manage tokens, see [How do I create and manage API tokens for the Luminous External API?]

Creating an API Token

In Luminous, go to Admin → Settings → API Tokens.
Click Create New API Token.
Enter a descriptive Token Label (e.g., Shopify Integration).
Optionally toggle Restrict customer PII on External API if you want addresses, emails, and phone numbers omitted or hashed in API responses (useful for GDPR compliance). This setting is permanent — it cannot be changed after creation.
Click Create Token.
Copy your token immediately — the full value is shown only once. After you leave the screen, the token is masked (only the first and last four characters are visible).

Using the Token

Add the token to each request:

Authorization: Bearer abc1••••••••••••••••••••••••••••••••••••••••••••••••••••••••xyz9
Content-Type: application/json
Accept: application/json

Security tip: Store your token in a password manager or environment variable — never in source code, email, or chat. Tokens are tied to a specific Luminous user account; delete tokens that are no longer in use.

Method 2 — OAuth 2.0 Access Token (Advanced)

You can also authenticate with a short-lived OAuth 2.0 Bearer token, using the same Authorization header.

Scope requirements:

Read-only endpoints (GET, HEAD) require the luminous:read scope.
Write endpoints (POST, PATCH, DELETE) require the luminous:write scope.
Without the luminous:pii scope, PII restriction is applied automatically.

OAuth tokens are validated and cached briefly to avoid repeated database lookups. Revoked or expired tokens are rejected within that short window.

If OAuth is not enabled on your account, only standard API tokens are accepted.

Error Responses

Status	Meaning
`401 Unauthorized`	Token missing, invalid, expired, or the token belongs to a different tenant
`403 — {"message": "Insufficient scope"}`	OAuth token lacks luminous:read (GET) or luminous:write (other methods).” Delete “If OAuth is not enabled on your account

All error responses are JSON:

{ "message": "Unauthorized" }

Token Management Tips

One token per integration — use distinct, clearly labeled tokens so you can revoke one without affecting others.
Rotate tokens regularly, especially after team-member changes.
PII restriction is set at creation — if you need to change it, delete the old token and create a new one.
The full token value is shown only once at creation time. If you lose it, delete and recreate the token.