Authentication
The LumoAuth API supports two authentication schemes:
| Scheme | Header format | When to use |
|---|---|---|
| API Key | Authorization: ApiKey lmk_… or X-API-Key: lmk_… | Server-to-server, CI/CD pipelines, admin scripts |
| Bearer Token | Authorization: Bearer eyJ… | OAuth 2.0 access tokens issued via any supported grant |
API Keys
API keys are long-lived credentials scoped to a organization. Every Admin API call can be authenticated with an API key.
API key via Authorization header
curl https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/users \
-H "Authorization: ApiKey lmk_abc123xyz..."
API key via X-API-Key header
curl https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/users \
-H "X-API-Key: lmk_abc123xyz..."
Generating API Keys
- Navigate to Settings → API Keys in your organization portal.
- Click Generate New API Key.
- Give the key a descriptive name (e.g.,
production-sync). - Copy the generated key — it is displayed only once.
warning
Store API keys in a secret manager (e.g., AWS Secrets Manager, Vault). Never commit them to source control.
API Key Format
Keys always start with lmk_ followed by a random string. Example: lmk_s3cr3t_abc123.
Bearer Tokens
Bearer tokens are short-lived JWTs or opaque tokens issued by the OAuth 2.0 token endpoint. Use them when authenticating on behalf of a user or for machine-to-machine flows via the Client Credentials grant.
Bearer token
curl https://app.lumoauth.dev/orgs/acme-corp/api/v1/oauth/userinfo \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
See OAuth 2.0 Token Endpoint for how to obtain tokens.
Authentication Errors
| Status | Error | Description |
|---|---|---|
401 | unauthorized | No credential provided, or the key/token is invalid or revoked |
403 | forbidden | Credential is valid but lacks the required permission or role |