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

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.