Core Concepts
These are the pieces of the LumoAuth model and how they fit together. If you have worked with OAuth or SAML before, most of this will be familiar — the multi-organization and Zanzibar pieces are the main new ones.
Organizations
An organization is an isolated environment within LumoAuth. Each organization owns its own:
- Users and user data
- Roles, permissions, and groups
- OAuth applications and clients
- Sign-in settings (MFA, social login, SSO)
- Audit logs and compliance data
- Custom domains and branding
Organizations are identified by a slug — a URL-friendly identifier like acme-corp. All organization-scoped resources are under the /orgs/{orgId}/ URL prefix.
If you sell to other companies, create one organization per customer. If you are a single team, you typically have one organization.
URL structure
/orgs/{orgId}/portal/ → organization admin dashboard
/orgs/{orgId}/portal/applications → OAuth application management
/orgs/{orgId}/portal/users → Users (tabs: Users, Invitations, Groups)
/orgs/{orgId}/portal/roles → Roles & permissions
/orgs/{orgId}/portal/settings/authentication → Sign-in settings
/orgs/{orgId}/portal/settings/login-page → Login page & emails
/orgs/{orgId}/api/v1/oauth/authorize → OAuth 2.0 authorize endpoint
/orgs/{orgId}/api/v1/oauth/token → OAuth 2.0 token endpoint
/orgs/{orgId}/api/v1/scim2.0/Users → SCIM provisioning endpoint
Users
A user represents a person who can authenticate with LumoAuth. Users belong to exactly one organization. A user has:
- Credentials — email/password, social accounts, passkeys
- Roles — one or more roles that grant permissions
- Groups — group memberships that grant roles by inheritance
- MFA authenticators — passkeys, LumoAuth app devices, authenticator apps, phone numbers, email codes, and recovery codes
- Sessions — active login sessions across devices
- Social accounts — linked accounts at identity providers (Google, GitHub, etc.)
User lifecycle
Invited / Registered → Email Verified → Active → (Blocked / Deleted)
Users can self-register, be invited by an admin, or be provisioned automatically via SCIM or JIT (just-in-time) provisioning from an external identity provider.
An account belongs to exactly one organization. The same email address can hold an account in several organizations (one per organization). Each of those accounts is joined through its own invitation or sign-up and has its own password and factors. The same email address can create only one organization through the public sign-up.
Roles and permissions
LumoAuth uses Role-Based Access Control (RBAC) as its default model for authorization.
- Permissions describe what action can be performed on what resource (e.g.,
user:read,organization:manage). - Roles are named bundles of permissions assigned to users (e.g.,
admin,editor,viewer). - System roles are predefined and cannot be deleted. Custom roles can be defined per organization.
Example
Role: "Editor"
Permissions:
- article:read
- article:write
- article:publish
- comment:read
- comment:write
Groups
Groups let you assign roles in bulk. Adding a user to a group gives them every role that the group has.
Group: "Engineering Team"
Roles: [Developer, Deployer]
Members: [alice@example.com, bob@example.com]
OAuth applications (clients)
An OAuth application — also called a client — represents an app that authenticates users through LumoAuth. Each application has:
- Client ID — public identifier
- Client Secret — confidential key, used only by server-side apps
- Redirect URIs — the callback URLs that OAuth is allowed to redirect to
- Grant types — which OAuth 2.0 flows the client can use
- Scopes — what the application is allowed to request
Application types
| Type | Grant types | Use case |
|---|---|---|
| Web application | Authorization Code | Server-rendered web apps that can hold a client secret |
| Single-page app (SPA) | Authorization Code + PKCE (a one-time secret that protects the sign-in code) | JavaScript apps — React, Vue, Angular |
| Native / mobile app | Authorization Code + PKCE | iOS, Android, desktop apps |
| Machine-to-machine | Client Credentials | Backend services, cron jobs, integrations |
| CLI / IoT device | Device authorization (sign in on another device) | Command-line tools, smart TVs, input-constrained devices |
| SAML application | SAML 2.0 Assertion | Enterprise SSO to third-party SaaS |
Scopes and claims
Scopes are permission strings the app requests at login time. Claims are the fields that end up in the ID token and userinfo response. The OIDC spec defines a standard set:
| Scope | Claims returned |
|---|---|
openid | Subject identifier (sub) — required for any OIDC request |
profile | Name, nickname, picture, etc. |
email | Email address, email verification status |
address | Postal address |
phone | Phone number |
Custom scopes can be defined per organization to control access to specific APIs.
Tokens
LumoAuth issues several token types, each with a different purpose:
| Token | Format | Purpose | Lifetime |
|---|---|---|---|
| Access token | JWT | Authorize API requests (Bearer token) | Short — minutes to hours |
| ID token | JWT | Identify the authenticated user to the app | Short |
| Refresh token | Opaque | Exchange for new access tokens without re-prompting the user | Long — days to months |
| Authorization code | Opaque | One-time code exchanged for tokens at the /token endpoint | Very short — minutes |
| Device code | Opaque | Device-flow polling code | Minutes |
A JWT (JSON Web Token) is a signed JSON payload. Your service can verify the signature offline with LumoAuth's public keys, then trust the claims inside — no network call needed per request.
Authentication flows
LumoAuth supports these OAuth 2.0 / OIDC flows:
| Flow | Best for | Description |
|---|---|---|
| Authorization Code | Server-rendered web apps | Browser redirect to LumoAuth, code exchanged server-side for tokens |
| Authorization Code + PKCE | SPAs, mobile apps | Same as above, plus a PKCE code verifier so a stolen code is useless |
| Client Credentials | Service-to-service | No user involved; the service authenticates with its own credentials |
| Device Authorization | CLIs, smart TVs | Device shows a short code; the user enters it on a second device |
| Refresh Token | All | Exchange a refresh token for a new access/ID token |
| CIBA (client-initiated backchannel authentication) | Decoupled auth | Client initiates login; user approves out-of-band (e.g., via a push) |
Organization portal sections
The organization portal at /orgs/{orgId}/portal/ groups its pages in the sidebar as follows (see the portal tour for every page, and the portal page → guide map for where each one is documented):
Home
- Dashboard (
/orgs/{orgId}/portal/) — sign-ins, active users, sign-ups, tokens, audit events and failure reasons over 24h to 90 days, top applications, and a setup checklist - Get started (
/orgs/{orgId}/portal/onboarding) — guided setup, quickstarts and your organization's credentials
AI Agents
- Agents (
/orgs/{orgId}/portal/agents) — agent registration and management; tabs for AAuth credentials, AAuth resources and Connections - Approvals (
/orgs/{orgId}/portal/approvals) — requests waiting on a human - MCP servers (
/orgs/{orgId}/portal/mcp-servers) — MCP server registration - Agent rules (
/orgs/{orgId}/portal/agents/policies) — access rules, auto-approve rules and cross-app access - Agent activity (
/orgs/{orgId}/portal/caep-dashboard) — fleet activity and security signals
Identity
- Users (
/orgs/{orgId}/portal/users) — users, invitations (/portal/users/invitations) and groups (/portal/groups) as tabs - Customer organizations (
/orgs/{orgId}/portal/organizations) — the companies and teams your product serves
Access control
- How access works (
/orgs/{orgId}/portal/access) — the three models side by side - Roles & permissions (
/orgs/{orgId}/portal/roles, permissions at/portal/permissions) — role definitions and the permission catalog; Draft with AI opens natural-language policy authoring (/portal/policies/author) - Relationships (
/orgs/{orgId}/portal/zanzibar/) — relationship-based access control - Attribute rules (
/orgs/{orgId}/portal/abac/) — attribute-based policies - Test access (
/orgs/{orgId}/portal/permissions/tester) — try authorization decisions live
Applications & developer tools
- Applications (
/orgs/{orgId}/portal/applications) — create, edit and delete OpenID Connect and SAML applications, rotate client secrets, manage per-application social login and branding - Quickstarts (
/orgs/{orgId}/portal/onboarding/quickstart), API keys (/portal/settings/api-keys), API explorer (/portal/developer/api-explorer), Test login (/portal/developer/test-login), JWT inspector (/portal/developer/jwt-inspector) and Endpoints & metadata (/portal/metadata)
Security
- Sign-in settings (
/orgs/{orgId}/portal/settings/authentication) — identity methods, login flow, password standards, MFA policy - Adaptive security (
/orgs/{orgId}/portal/settings/adaptive-auth) — risk-based sign-in decisions - Signing keys (
/orgs/{orgId}/portal/signing-keys) — token signing keys and rotation - Audit logs (
/orgs/{orgId}/portal/audit-logs) — append-only audit trail
Settings
- Integrations (
/orgs/{orgId}/portal/integrations) — one hub with a section per capability: enterprise SSO (SAML at/portal/saml-idps, OIDC at/portal/oidc-idps), social login, LDAP / Active Directory, SCIM (inbound and outbound), observability (log sinks such as Datadog, Axiom and Honeycomb), webhooks and more - Login page & emails (
/orgs/{orgId}/portal/settings/login-pageand/portal/settings/email-templates) — branding of the hosted pages and the transactional emails - Custom domains (
/orgs/{orgId}/portal/custom-domains), Billing (/portal/billing) and Data export (/portal/data-export)
GDPR & privacy
- Privacy overview (
/orgs/{orgId}/portal/gdpr), Subject requests (/portal/gdpr/dsr) and Consent records (/portal/gdpr/consent-records)
Help
- Help for this page opens the guide for the current page; Documentation opens this site
Next steps
- Your first 15 minutes in the portal — hands-on setup walkthrough
- Authentication Overview — all supported auth methods
- Access Control Overview — authorization models in detail
Standards used on this page
| Plain name | Standard |
|---|---|
| Device authorization (sign in on another device) | RFC 8628 |
| JSON Web Token (JWT) | RFC 7519 |
See the standards reference for what each one covers and how LumoAuth uses it.