Quick Start Guide

This guide walks through signing up, configuring an organization, registering an OAuth application, and running an end-to-end login flow.

---

Prerequisites

• A LumoAuth account — sign up at app.lumoauth.dev
• An HTTP client (curl, Postman, or equivalent)

---

Step 1: Sign up and create your organization

1. Go to app.lumoauth.dev and create an account.
2. During onboarding, you will create your first organization — an isolated environment that holds your users, apps, and settings.
3. Choose an organization ID (e.g., acme-corp). This becomes part of all your URLs, so pick something URL-safe and stable.

Your organization is now live at:

https://app.lumoauth.dev/orgs/acme-corp/portal/

What is an organization?

An organization is an isolated identity environment. All users, applications, roles, and settings belong to one organization and are invisible to other organizations on the platform. If you are a B2B SaaS vendor, create one organization per customer.

---

Step 2: Explore the organization portal

Navigate to the portal at /orgs/acme-corp/portal/. The dashboard links to:

• Applications — register OAuth and SAML applications
• Access Management — users, roles, groups, permissions
• Configuration — authentication, social login, MFA, SSO
• Security — audit logs, signing keys, custom domains

---

Step 3: Configure authentication

Go to Configuration → Auth Settings at /orgs/acme-corp/portal/configuration/auth-settings.

Basic settings

• Allow registration — enable user self-registration
• Require email verification — users must verify email before gaining access
• Password policy — minimum length and complexity rules

Enable social login (optional)

1. Go to Configuration → Social Login.
2. Select a provider (e.g., Google).
3. Enter the OAuth client ID and secret from the provider's developer console.
4. Save and enable.

Configure MFA (optional)

1. Under Multi-Factor Authentication, enable TOTP, SMS, or email codes.
2. Optionally enable Adaptive MFA to trigger MFA only on risky sign-ins.

---

Step 4: Register an OAuth application

Go to Applications at /orgs/acme-corp/portal/applications.

1. Click Create Application.
2. Fill in:
   • Name: My Web App
   • Redirect URI: https://myapp.example.com/callback
   • Grant Types: Authorization Code
3. Save. You will receive a Client ID and Client Secret.

The Client ID is a public identifier. The Client Secret must be stored only on your server — never in a browser or mobile app.

---

Step 5: Authenticate a user

Start the OAuth flow

Redirect the user to the authorize endpoint:

https://app.lumoauth.dev/orgs/acme-corp/api/v1/oauth/authorize?
  response_type=code&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://myapp.example.com/callback&
  scope=openid profile email&
  state=RANDOM_STATE

The user logs in at LumoAuth. On success, LumoAuth redirects back to your redirect_uri with a short-lived authorization code.

The state parameter is an opaque value your app generates and checks on return. It prevents cross-site request forgery — an attacker cannot forge an OAuth callback for a different user.

Exchange the code for tokens

Your server sends the code to the token endpoint:

curl -X POST https://app.lumoauth.dev/orgs/acme-corp/api/v1/oauth/token \
  -d grant_type=authorization_code \
  -d code=AUTHORIZATION_CODE \
  -d redirect_uri=https://myapp.example.com/callback \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET

Response:

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "def...",
  "id_token": "eyJ..."
}

• access_token — used as a Bearer token to call protected APIs
• id_token — a JWT identifying the authenticated user (for your app to consume)
• refresh_token — long-lived token used to get new access tokens without re-prompting the user

---

Step 6: Verify the setup

Check OIDC discovery

Every OIDC provider publishes a discovery document at a well-known URL. It lists the endpoints, supported flows, and public signing keys.

curl https://app.lumoauth.dev/orgs/acme-corp/api/v1/.well-known/openid-configuration

Get user info

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  https://app.lumoauth.dev/orgs/acme-corp/api/v1/oauth/userinfo

---

What's next?

Feature	Guide
Add social login	Social Login Guide
Enable MFA	MFA Guide
Set up adaptive authentication	Adaptive MFA Guide
Configure RBAC	Roles & Permissions
Invite users	User Invitations
Set up SCIM provisioning	SCIM 2.0 Guide
Enable GDPR compliance	GDPR Guide
Connect webhooks	Webhooks Guide