> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Lumos API v1

> What the v1 API covers, and how to connect your first app.

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

```text Base URL theme={null}
https://api.lumos.com
```

Every v1 path starts with `/v1`. Authenticate with a bearer token, as
[Authentication](https://docs.lumos.com/reference/v1/authentication.md) 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.

**1. Find the integration**

Search the catalog with [List Integrations](https://docs.lumos.com/api-reference/v1/integrations/list-integrations.md). The
`query` parameter matches both the `app_class_id` and the display name.

```bash theme={null}
curl -s 'https://api.lumos.com/v1/integrations?query=okta' \
  --header 'Authorization: Bearer lsk_your_token'
```

**2. Read the credentials it expects**

[Get Integration Connection Schema](https://docs.lumos.com/api-reference/v1/integrations/get-integration-connection-schema.md)
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](https://registry.terraform.io/providers/teamlumos/lumos/latest/docs).

```bash theme={null}
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`.

**3. Connect it**

Send the credentials that the schema lists to [Create App](https://docs.lumos.com/api-reference/v1/apps/create-app.md).

```bash theme={null}
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.

**4. 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](https://docs.lumos.com/api-reference/v1/apps/trigger-app-sync.md) with
`skip_first_sync_review: true`. To review the rules first, start it from the Lumos UI instead.
[The first sync](https://docs.lumos.com/reference/v1/objects/app.md#the-first-sync) covers the review.

```bash theme={null}
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](https://docs.lumos.com/api-reference/v1/apps/get-app.md). To sync again later, call `POST /v1/apps/{app_uuid}:sync`
and poll the operation it returns, as [Long-running operations](https://docs.lumos.com/reference/v1/long-running-operations.md)
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](https://docs.lumos.com/reference/v1/objects/app.md#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](https://docs.lumos.com/reference/v1/pagination.md), including why a short page doesn't mean the end of the
  results.
* [Errors](https://docs.lumos.com/reference/v1/errors.md), 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](https://docs.lumos.com/api-reference/v1/apps/list-apps.md) and [Get App](https://docs.lumos.com/api-reference/v1/apps/get-app.md)
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.