LumoAuth API Reference

The LumoAuth API is organized around REST. All API endpoints are organization-scoped, accept JSON-encoded request bodies, return JSON-encoded responses, and use standard HTTP response codes and verbs.

Just getting started?

Pick the path on the Start page that matches what you're building — each one covers the API end-to-end for your use case.

Base URL

Every API request is scoped to an organization using the organization ID:

https://app.lumoauth.dev/orgs/{org_id}/api/v1/

For EU-region organizations:

https://eu.app.lumoauth.dev/orgs/{org_id}/api/v1/

curl

Example Request

curl https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/users \
  -H "Authorization: ApiKey lmk_abc123xyz" \
  -H "Content-Type: application/json"

Node

const resp = await fetch("https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/users", {
  method: "GET",
  headers: { "Authorization": process.env.LUMO_AUTH, "Content-Type": "application/json" }
});
console.log(await resp.json());

Python

import os, requests

resp = requests.get(
    "https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/users",
    headers={"Authorization": os.environ["LUMO_AUTH"]}
)
print(resp.json())

Go

import (
    "io"
    "net/http"
    "os"
    "strings"
)

req, _ := http.NewRequest("GET", "https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/users", nil)
    req.Header.Set("Authorization", os.Getenv("LUMO_AUTH"))
resp, err := http.DefaultClient.Do(req)
if err != nil { panic(err) }
defer resp.Body.Close()
out, _ := io.ReadAll(resp.Body)
fmt.Println(string(out))

Authentication

The Admin API accepts three credentials. Pick by who is calling:

Caller	Credential	Header
Server, CI pipeline, script	API key (lmk_…), scoped per resource	Authorization: ApiKey lmk_... or X-API-Key: lmk_...
App acting for a signed-in administrator	OAuth 2.0 access token carrying an admin scope	Authorization: Bearer eyJ...
The portal or a first-party page on the LumoAuth host	Session cookie (plus X-Requested-With on writes)	sent by the browser

API keys and Bearer tokens are stateless: they never receive a session cookie and are refused on the portal and account pages. Scopes are enforced per resource and a read scope never authorises a write.

Learn more about authentication →

Core Concepts

Organizations

LumoAuth is a multi-organization identity platform. Each organization is an isolated environment with its own users, applications, and configuration, identified by a slug (e.g., acme-corp).

Users

Users are the identities that authenticate with your applications. Each user belongs to one organization and can have roles, groups, and custom attributes assigned.

Roles & Permissions

Roles are collections of permissions assigned to users or groups. Permissions define specific actions on resources (e.g., read:reports).

Groups

Groups organize users and carry role assignments. Users inherit all roles from their groups.

OAuth Clients

OAuth clients represent applications that authenticate users. Each client has a client ID, secret, redirect URIs, and allowed scopes.

Resource Hierarchy

API Categories

Category	Description
Users	Create, update, delete users; manage roles, groups, permissions, and passwords.
Groups	Organize users into groups with collective role assignments.
Roles	Define roles and associate permissions; manage role members.
Permissions	Fine-grained permission definitions, usage tracking, and scope management.
OAuth 2.0	Authorization, token, introspection, and OIDC endpoints.
OAuth Clients	Manage OIDC/OAuth 2.0 applications — enable/disable, rotate secrets, manage scopes.
AI Agents	Machine identities, capabilities, and lifecycle management.
JIT Permissions	Just-in-time elevated access for AI agents.
AAuth Protocol	Cryptographic protocol for agent authorization.
Ask API	Natural-language authorization for LLMs.
Authorization (RBAC / ABAC)	Policy-based access control — check, bulk check, policies.
Zanzibar (ReBAC)	Check endpoint for relationship-based access control.
SAML 2.0	IdP and SP endpoints, metadata.
SCIM 2.0	Directory sync — provision users and groups.
Webhooks	Real-time event delivery to your endpoints.
Audit Logs	Immutable organization-scoped audit trail with export and retention management.
Sessions	Active session and token management; session statistics.
Social Providers	Configure Google, GitHub, Microsoft, and other social login providers.
Settings	Organization configuration — general, authentication, security, and email settings.

Request & Response Format

All API requests must include Content-Type: application/json. All responses are JSON.

Endpoint Pattern

https://app.lumoauth.dev/orgs/{org_id}/api/v1/{resource}

Success Response

200 OK

{
  "id": "01JF3K...",
  "email": "user@example.com",
  "name": "John Doe",
  "createdAt": "2026-01-15T10:30:00Z"
}

Error Response

4xx / 5xx

{
  "error": "not_found",
  "message": "User not found",
  "status": 404
}

HTTP Status Codes

Code	Meaning
200	OK — request succeeded
201	Created — resource created
204	No Content — success with empty body
400	Bad Request — validation error
401	Unauthorized — missing or invalid credentials
403	Forbidden — insufficient permissions
404	Not Found — resource does not exist
409	Conflict — duplicate resource
422	Unprocessable Entity — semantic validation failure
429	Too Many Requests — rate limit exceeded
500	Internal Server Error