Lumos API v1

Lumos API v1 is the programmatic interface to your connected apps, the entitlements on them, and the workflows that grant access to those entitlements.

Base URL

https://api.lumos.com

Every v1 path starts with /v1. Authenticate with a bearer token, as Authentication describes.

What’s in v1

Group	What it covers
Access Policies	Grants of apps, and optionally specific entitlements on them, to the identities that match a condition.
Access Requests	Requests for access to an app, or to specific entitlements on it, for you or for another user.
Access Reviews	Campaigns that review who has access to what. v1 syncs an app review and reads its subjects. Lumos enables these endpoints per organization. To enable them, contact your Lumos representative.
Accounts	An identity’s account in an app, and the entitlements that account holds.
Activity Logs	Entries that record the actions across your organization’s apps and identities.
App Categories	The fixed set of categories an app can belong to.
Apps	The apps you have connected. Each app is one connected instance of an integration in your organization.
Custom Attributes	The definitions of extra fields your organization keeps on users.
Entitlements	The grantable units of access on an app: roles, licenses, groups, access rights.
Groups	The groups Lumos syncs from your connected apps, and their members.
Identity Events	The changes Lumos detects on your organization’s identities, such as a change to a status or a group membership.
Inline Webhooks	The webhooks your organization has configured in Lumos.
Integrations	The catalog of services Lumos can connect to, and the credentials each one needs.
Knowledge	Documents and notes that Lumos agents use when they answer access questions.
Lifecycle Management	Offboardings of identities, run right away or at a scheduled time.
Meta	Two endpoints that check that the API is reachable and your token works.
Operations	Work that continues after the request that started it has returned, such as an app sync.
Pre-Approval Rules	Rules that pre-approve matching access requests for an app. Lumos enables these endpoints per organization.
Tasks	Work Lumos assigns to a user or group, such as approving an access request.
Users	The people in your organization, and their Lumos roles.
Workflows	Reusable definitions of the steps Lumos runs to approve, provision, or deprovision.

Connect your first app

Connecting an app takes three calls, and a fourth call starts its first sync. The first two calls exist so that you never have to hardcode the credential fields of each integration.

Find the integration

Search the catalog with List Integrations. The query parameter matches both the app_class_id and the display name.

curl -s 'https://api.lumos.com/v1/integrations?query=okta' \
  --header 'Authorization: Bearer lsk_your_token'

Read the credentials it expects

Get Integration Connection Schema returns the JSON schema of the auth and settings fields that the integration needs. Use it to build a connect form, or to write the auth and settings of a lumos_app resource in the Lumos Terraform provider.

curl -s 'https://api.lumos.com/v1/integrations/okta.com/connection-schema' \
  --header 'Authorization: Bearer lsk_your_token'

If Lumos can’t describe an integration’s connection schema yet, this endpoint returns 404.

Connect it

Send the credentials that the schema lists to Create App.

curl -s -X POST 'https://api.lumos.com/v1/apps' \
  --header 'Authorization: Bearer lsk_your_token' \
  --header 'Content-Type: application/json' \
  --data '{
    "app_class_id": "okta.com",
    "auth": { "...": "values from the connection schema" }
  }'

If the credentials validate right away, the call connects the app. If the integration needs browser consent, finish connecting the app in the Lumos UI.

Start its first sync

A new app’s first sync waits for an admin to review the app’s identity matching rules. To start it without the review, call Trigger App Sync with skip_first_sync_review: true. To review the rules first, start it from the Lumos UI instead. The first sync covers the review.

curl -s -X POST 'https://api.lumos.com/v1/apps/1a2b3c4d-5e6f-7890-abcd-ef1234567890:sync' \
  --header 'Authorization: Bearer lsk_your_token' \
  --header 'Content-Type: application/json' \
  --data '{ "sync_type": "full-sync", "skip_first_sync_review": true }'

After the first sync starts, track it with sync_status on Get App. To sync again later, call POST /v1/apps/{app_uuid}:sync and poll the operation it returns, as Long-running operations describes. To list only the apps you connect this way, for example to reconcile them with a Terraform configuration, use the filters that Reconciling apps connected through the API describes.

Pagination and errors

Every list endpoint pages the same way, and every error uses the same envelope. Each has one behavior to know before you build:

Pagination, including why a short page doesn’t mean the end of the results.
Errors, including which field to branch on.

Timestamps

v1 returns every timestamp in UTC, as ISO 8601 with a Z suffix, such as 2026-01-15T18:30:00Z.

Requesting fields with `expand`

Read endpoints keep responses small. They omit expensive fields unless you request them. For example, List Apps and Get App return the base schema. To include admins and custom_attributes, pass ?expand=admins,custom_attributes. Lumos checks each field in expand against your permissions. If you can’t read a field, the response omits it and the request still succeeds. A 200 doesn’t prove that every field you requested is present, so check for the key instead of assuming that it’s there.

Quick Start

Lumos API

API Reference

Guides

Migrate from v0

Lumos Connectors

Webhooks

Tools

Lumos API v1

What’s in v1

Connect your first app

Timestamps

Requesting fields with `expand`

​What’s in v1

​Connect your first app

​Pagination and errors

​Timestamps

​Requesting fields with expand

What’s in v1

Connect your first app

Pagination and errors

Timestamps

Requesting fields with `expand`