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
Authentication 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 live under the /orgs/{orgId}/ URL prefix.

If you are a B2B SaaS vendor, 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/access-management/users   → user management
/orgs/{orgId}/portal/access-management/roles   → role management
/orgs/{orgId}/portal/access-management/groups  → group management
/orgs/{orgId}/portal/configuration/            → organization settings
/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 methods — TOTP, SMS, email, or backup codes
Sessions — active login sessions across devices
Social accounts — linked identity provider accounts (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.

Roles and permissions

LumoAuth uses Role-Based Access Control (RBAC) as the default authorization model.

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 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 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	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 (RFC 8628)	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 gate API-specific access.

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, RFC 7519) 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	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/ is organized into these areas:

Dashboard

Overview page with key metrics and recent activity.

Applications (developer)

/orgs/{orgId}/portal/applications — list and manage OAuth and SAML applications
Create, edit, and delete OAuth clients
Configure SAML service providers
Manage per-app social login settings
Rotate client secrets

Access Management

/orgs/{orgId}/portal/access-management/users — user CRUD, search, invitations
/orgs/{orgId}/portal/access-management/roles — role definitions and permission assignment
/orgs/{orgId}/portal/access-management/groups — groups
/orgs/{orgId}/portal/access-management/permissions — permission definitions
/orgs/{orgId}/portal/access-management/zanzibar — fine-grained relationship-based access control
/orgs/{orgId}/portal/access-management/abac — attribute-based policies
/orgs/{orgId}/portal/access-management/policy-author — natural-language policy authoring
/orgs/{orgId}/portal/access-management/permission-tester — try authorization decisions live

Configuration

/orgs/{orgId}/portal/configuration/auth-settings — authentication methods, MFA, adaptive auth
/orgs/{orgId}/portal/configuration/social-login — social identity providers
/orgs/{orgId}/portal/configuration/saml-idp — SAML IdP configuration
/orgs/{orgId}/portal/configuration/oidc-idp — external OIDC IdPs
/orgs/{orgId}/portal/configuration/ldap — LDAP / Active Directory
/orgs/{orgId}/portal/configuration/email-templates — email template customization
/orgs/{orgId}/portal/configuration/webhooks — webhook event subscriptions

Security and Compliance

/orgs/{orgId}/portal/signing-keys — JWT signing key management and rotation
/orgs/{orgId}/portal/custom-domains — branded login domain configuration
/orgs/{orgId}/portal/audit-logs — append-only audit trail
/orgs/{orgId}/portal/gdpr — GDPR data subject requests and privacy tools

Observability

/orgs/{orgId}/portal/observability — Datadog and Axiom integration

AI Agents

/orgs/{orgId}/portal/ai-agents — agent management and MCP configuration

Next steps

Configure Your Organization — hands-on setup walkthrough
Authentication Overview — all supported auth methods
Access Control Overview — authorization models in detail

Organizations​

URL structure​

Users​

User lifecycle​

Roles and permissions​

Example​

Groups​

OAuth applications (clients)​

Application types​

Scopes and claims​

Tokens​

Authentication flows​

Organization portal sections​

Dashboard​

Applications (developer)​

Access Management​

Configuration​

Security and Compliance​

Observability​

AI Agents​

Next steps​