Skip to main content
The sync endpoint lets you trigger an integration sync on demand — a fresh pull of an app’s accounts and entitlements into Lumos — from a script, a CI pipeline, or a scheduler. You don’t need to manage the integration’s connection through the API to use it: it works for integrations connected in the Lumos UI, via the Integrations API, or via Terraform.

​
Overview

A sync is how Lumos pulls an integration’s current data - accounts, groups, and entitlements - so what you see in Lumos matches what’s in the app. Lumos already syncs every connected integration on a regular schedule, and connecting or reconnecting an integration triggers a sync automatically. The sync endpoint covers the moments in between: when you’ve just made changes in the app and want them reflected in Lumos now, rather than at the next scheduled sync. Typical triggers:
  • Right after automation finishes a change in the app - an offboarding wave, a role migration, a department reorg.
  • Right after terraform apply connects an integration, from the same CI pipeline.
  • Before kicking off an Access Review, so reviewers see current data.
  • On your own schedule, if you want a specific integration refreshed more often.

​
Before you start

You need:
  • An API token. Create one in the Lumos UI under Settings → API Tokens. The token is shown once - copy it somewhere safe. Examples below read it from a LUMOS_API_TOKEN environment variable.
  • Permission to manage integrations. A token acts as the user who created it, so that user must be an admin with permission to manage integrations. Without it, calls return 403.
  • A connected integration. Connected in the Lumos UI, via the API, or via Terraform — any of them works.
  • The base URL https://api.lumos.com. All paths below are relative to it.

​
Authentication

Send your token as a bearer token in the Authorization header on every request:
A request with a missing or invalid token returns 401.

​
Concept-to-endpoint map

​
Core workflow

​
1. Find the integration’s id

Syncs are triggered by the integration’s id (a UUID). List your apps and pick the one you want — ?disconnected=false narrows the list to connected ones:
(Response trimmed to the relevant fields.) If you connected the integration programmatically you already have this id: it’s the id returned by the connect call, and the id attribute of the lumos_app Terraform resource (terraform state show lumos_app.okta).

​
2. Trigger the sync

Call the sync endpoint with the sync_type you want. Today the only supported value is full_sync — a full re-pull of the integration’s accounts, groups, and entitlements:
Precondition: the integration is connected (or its last sync failed — retrying after a failure is allowed). A 202 Accepted confirms the sync was launched:
sync_type is required even though there’s one value today — new sync kinds will be added as additional values, so your request shape won’t change.

​
3. Understand what happens next

The sync runs asynchronously — the 202 means it was launched, not that it finished. How long it takes depends on the integration and the amount of data; when it completes, the refreshed accounts and entitlements are visible in Lumos. Only one sync runs at a time per integration. If a sync is already in progress — including a scheduled one Lumos started — the call returns 409 Conflict:
Wait for the running sync to finish, then retry. Since the running sync is already pulling the app’s current data, a 409 usually means the refresh you wanted is underway anyway.

​
Handling errors

Errors return the relevant HTTP status and a JSON body with a human-readable detail, plus machine-readable type and code fields your automation can branch on.

​
Next steps