Skip to main content

OAuth 2.0 API

LumoAuth implements OAuth 2.0 and OpenID Connect. OAuth 2.0 is defined by RFC 6749 — the OAuth 2.0 Authorization Framework, the core specification that defines the authorize and token endpoints and the standard grant types. OpenID Connect adds an identity layer on top, issuing an id_token alongside the access token. These endpoints let your applications authenticate users, obtain tokens, and access protected resources.

Available Endpoints​

GET /orgs/{orgId}/api/v1/oauth/authorize

Starts the OAuth flow. Redirects the user to authenticate and grant permissions. Details.

POST /orgs/{orgId}/api/v1/oauth/token

Exchanges authorization codes for tokens, refreshes tokens, or uses client credentials. Details.

POST /orgs/{orgId}/api/v1/oauth/introspect

Validates tokens and returns their metadata. Implements RFC 7662 — OAuth 2.0 Token Introspection: an authorized resource server calls /introspect to ask LumoAuth whether a token is still valid. Details.

GET / POST /orgs/{orgId}/api/v1/oauth/userinfo

Returns information about the authenticated user or agent. Details.

POST /orgs/{orgId}/api/v1/connect/register

Registers new OAuth clients programmatically. Implements RFC 7591 — OAuth 2.0 Dynamic Client Registration: clients register themselves programmatically instead of being created manually in an admin UI. Details.

Supported Grant Types​

LumoAuth supports the following OAuth 2.0 grant types:

Grant TypeDescriptionUse Case
authorization_codeUser-interactive flow with redirectsWeb apps, SPAs, mobile apps
client_credentialsMachine-to-machine authenticationBackend services, APIs, cron jobs
refresh_tokenObtain a new access token without re-prompting the userMaintaining long-lived sessions
urn:ietf:params:oauth:grant-type:token-exchangeExchange one token for another (RFC 8693 — OAuth 2.0 Token Exchange: lets a service swap one token for another, the mechanism behind delegation and impersonation)Service-to-service delegation, impersonation

Organization-Scoped URLs​

All OAuth endpoints are scoped to a specific organization via the {orgId} path parameter. This ensures isolation between organizations: users, clients, and tokens from one organization cannot be used in another.

What is an Organization?

An organization represents an isolated environment in LumoAuth. Each organization has its own users, applications, roles, and configuration. It is identified by a unique slug (e.g., acme-corp).

Authentication Methods​

When calling the token endpoint, you can authenticate your client using:

curl -X POST https://app.lumoauth.dev/orgs/acme-corp/api/v1/oauth/token \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -d "grant_type=client_credentials"

Request Body Parameters​

curl -X POST https://app.lumoauth.dev/orgs/acme-corp/api/v1/oauth/token \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Response Format​

Successful token responses follow the OAuth 2.0 specification:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4...",
  "scope": "openid profile email",
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Next Steps​