About Lumos
Lumos is an identity governance and app management platform. The Serval Lumos integration connects to the Lumos REST API to read your organization’s directory and app data: users, apps, accounts, and groups, plus the Lumos AppStore, including each app’s request-flow approvers and requestable permissions. Access is read-only. Serval stores your API token encrypted and attaches it to every request automatically, so workflow code never sees the raw token. Serval only ever sends the token to one host for this integration: api.lumos.com. Authentication: API token (bearer). You paste a Lumos API token (starts with lsk_) into Serval’s connect form; there is no OAuth flow. Data sync: On demand only. There is no background sync - Lumos data is fetched live whenever a workflow runs.What the Lumos integration enables
| Capability | Description |
|---|---|
| List Lumos AppStore Apps | Page through all apps available in the Lumos AppStore, optionally filtered by a name search. Returns each app’s ID, label, status, and category. Part of the AppStore bundle. |
| Get Lumos App Approvers | Fetch the AppStore request-flow settings for a Lumos app by ID, returning its stage-1 approvers, stage-2 approvers, admins, and whether manager or additional approval is required. Part of the AppStore bundle. |
| List Lumos App Requestable Permissions | Page through the requestable permissions for a Lumos AppStore app by ID. Returns each permission’s label, type, AppStore visibility, manager-approval setting, and its stage-1 and stage-2 approvers. Part of the AppStore bundle. |
| List Lumos Accounts | Page through accounts in Lumos, optionally filtered by app ID or account lifecycle status (for example ACTIVE, SUSPENDED, or DEACTIVATED). Returns each account’s ID, app, email, name, and status. Part of the Directory & Apps bundle. |
| List Lumos Users | Page through users in the Lumos organization, optionally filtered by a search against name and email. Returns each user’s ID, email, name, and status. Part of the Directory & Apps bundle. |
| List Lumos Groups | Page through groups in Lumos, optionally filtered by group name or app ID. Returns each group’s ID, name, sourcing app, description, and integration-specific ID. Part of the Directory & Apps bundle. |
| List Lumos Apps | Page through all apps Lumos knows about for the organization, optionally filtered by a name search. Returns each app’s ID, label, status, category, and app class ID. Part of the Directory & Apps bundle. |
| Get Lumos App | Fetch a single Lumos app by its ID, returning its full details. Part of the Directory & Apps bundle. |
| Lumos API request | Typed action for custom workflows covering the integration’s read endpoints: the current user, users, apps, accounts, groups, AppStore apps, per-app request-flow settings, and requestable permissions. |
Get your credentials
You need an active Lumos organization and a Lumos API token, which starts with lsk_. Tokens inherit and retain the permissions of the user who creates them, so create the token from an admin or service account whose permissions cover the data your workflows need (admin access is required to create API tokens in Lumos). Lumos walks through token creation in its API Quick Start guide; the REST API guide has more background.Open the API Tokens page in Lumos
Sign in to Lumos and go to Settings, then API Tokens, at the Lumos API Tokens settings page.
Create a token
Click “Add API Token”, enter a name and a description, then click “Create API Token.”
Copy the token immediately
Copy the token that starts with lsk_. Lumos only shows the API token at creation time, so store it securely before closing the dialog.
Connect in Serval
Paste your token into the API Token field
The form has a single field, API Token (entered like a password, hidden as you type), with the helper text: “Your Lumos API token (starts with lsk_). Generate one from the API Tokens page in Lumos settings.”
Submit and let the health check confirm
Save the form. Serval does not validate the token’s format at this point - a typo is accepted here and only surfaces when the automatic health check runs (see the next section). If the connection cannot be saved at all, you may see “Failed to connect service” or “Failed to install integration”.
Verifying the connection
The Lumos integration has one health check, Get Current Lumos User. It uses your stored token to fetch the Lumos user who created the token, proving the integration is configured and the token is valid. It runs automatically after you connect or update the integration, and you can also trigger it from the app instance page.- On success: “Successfully connected to Lumos as [email].” (If the token’s user has no email, it reads “Successfully connected to Lumos.”)
- On failure: “Unable to fetch the current Lumos user. Please verify your API token is valid.”
Gotchas and troubleshooting
Lumos shows the API token only once
Lumos shows the API token only once
The token (lsk_…) is displayed only at creation time on the Lumos API Tokens page. Copy it before closing the dialog; if it is lost you must create a new token and update the Serval connection with it.
Tokens inherit and retain the creator's permissions
Tokens inherit and retain the creator's permissions
Lumos API tokens inherit and retain the permissions of the user who created them. Create the token from a service or admin account whose permissions match what your workflows need, and rotate the token if that person leaves or changes roles.
The connect form does not validate the token
The connect form does not validate the token
The API Token field has no format check, and the lsk_ prefix is not enforced. A typo or truncated paste is accepted at connect time and only surfaces when the “Get Current Lumos User” health check fails with: “Unable to fetch the current Lumos user. Please verify your API token is valid.” If you see that message right after connecting, re-copy the token from Lumos and replace it in Serval.
Access is read-only
Access is read-only
The integration covers reading Lumos data: users, apps, accounts, groups, and AppStore information. Lumos write operations (such as creating apps or uploading accounts) are not available through the integration.
List results come back in pages
List results come back in pages
Lists of users, apps, accounts, groups, and AppStore data are returned one page at a time, with up to 100 items per page (50 by default) and a page count included in each response. The prebuilt Serval workflows page through results for you; custom workflows need to request each page until the last one is reached.
Need help? Contact support@serval.com for assistance with your Lumos integration.

