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 track that matches what you're building — each one walks you through the API end-to-end for your use case.

Base URL

Every API request is scoped to a 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/

Example Request

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

Authentication

The LumoAuth Admin API supports two authentication methods:

Method	Header	Use case
API Key	Authorization: ApiKey lmk_... or X-API-Key: lmk_...	Server-to-server, CI/CD
Bearer Token	Authorization: Bearer eyJ...	OAuth 2.0 access tokens

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 agent authorization protocol.
Ask API	Natural-language authorization for LLMs.
Authorization (RBAC / ABAC)	Policy-based access control — check, bulk check, policies.
Zanzibar (ReBAC)	Relationship-based access control check.
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