Skip to main content

​
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

CapabilityDescription
List Lumos AppStore AppsPage 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 ApproversFetch 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 PermissionsPage 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 AccountsPage 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 UsersPage 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 GroupsPage 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 AppsPage 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 AppFetch a single Lumos app by its ID, returning its full details. Part of the Directory & Apps bundle.
Lumos API requestTyped 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.
These workflows, along with the typed Lumos API request action, cover the read endpoints Serval models from the Lumos API. Lumos write endpoints are not included. You can install the prebuilt workflows from Workflows, then Installable in Serval, or build your own with the workflow builder.

​
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.
1

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.
2

Create a token

Click “Add API Token”, enter a name and a description, then click “Create API Token.”
3

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.
4

Bring the token to Serval

Paste the token into the API Token field in Serval’s Lumos connect form (next section).
Lumos shows the token only once, at creation. If you lose it, you cannot view it again - you must create a new token.
Because tokens carry their creator’s permissions, prefer a service or admin account over a personal one, and plan to rotate the token if that person leaves or changes roles.

​
Connect in Serval

1

Open the Lumos connect form

In Serval, add the Lumos integration to open its connect form.
2

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.”
3

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”.
When you later edit an existing connection, the saved token appears as a masked value - bullets plus its last 4 characters - that you cannot type into directly. To rotate the token, click the pencil icon (on the connection settings page) or the Replace button (on the reconnect form) to get an empty “Enter new value” box, then paste the complete new lsk_ token and save. Leaving the token untouched, or saving while the replacement box is still empty, keeps your existing stored token. If an update fails, Serval shows “Failed to update integration” or “Failed to update configuration”, depending on which form you used.

​
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.”
A passing health check proves the token works, not that it can see everything. Tokens carry the permissions of the user who created them, so if the check is green but a workflow comes back with missing or empty Lumos data, check whether the token’s creator has access to that data in Lumos.

​
Gotchas and troubleshooting

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.
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 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.
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.
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.