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. It also writes to the AppStore request flow: Serval can submit an access request on a user’s behalf and act on the Lumos approval tasks that result, so a requester and an approver can both stay in Serval. Lumos remains the system of record - it evaluates the request against its own policy, records the approval decision, and provisions the access. Serval does not run the approval workflow, it surfaces and acts on Lumos tasks. 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, so app and permission lookups always reflect the current AppStore rather than a cached copy.

​
What the Lumos integration enables

These workflows, along with the typed Lumos API request action, cover the endpoints Serval models from the Lumos API. You can install the prebuilt workflows from Workflows, then Installable in Serval, or build your own in Catalyst. The four bundles are meant to be installed in layers. Access Requests and Approvals together give you the end-to-end flow - resolve the app and permission, submit the request, then surface and resolve the resulting approval task. AppStore and Directory & Apps are read-only lookups you can install on their own if you only want Serval to answer questions about Lumos. A typical end-to-end request looks like this:
1

Resolve what the user asked for

Run List Lumos AppStore Apps to find the app, then Search Lumos Requestable Permissions to find the specific permission. Both query Lumos live, so a newly added app or permission is immediately requestable.
2

Confirm the details

Collect the target user, the business justification, and the access duration before submitting. Lumos shows the justification to approvers.
3

Submit the request

Run Create Lumos Access Request. Lumos returns one access request per requested permission, and then evaluates its own approval policy.
4

Surface the approval

Run List Lumos Approval Tasks to find pending tasks and route each one to its assignee in Serval.
5

Let the approver act in Serval

Run Approve Lumos Task or Deny Lumos Task, with a comment to record the reasoning in Lumos. Lumos records the decision and provisions the access.
6

Report status back

Run Get Lumos Access Request to tell the requester where things stand without sending them to Lumos.

​
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.
Lumos authorizes task actions against the user who owns the API token. Completing, dismissing, or reassigning a task returns 403 unless that user is an assignee of the task or a Lumos domain admin. If approvals fail for some tasks but not others, this is usually why - use an admin token, or route each task to a Serval workflow that runs with a token that can act on it.
When Serval surfaces pending Lumos approval tasks, approvers will also receive Lumos’s own approval notifications unless those are disabled in Lumos. Turn off Lumos approval notifications for the apps Serval fronts, otherwise every approver gets pinged twice for the same decision.
“List Lumos Approval Tasks” returns only the tasks assigned to the API token’s own user by default. Enable Show All Tasks to see the whole domain’s queue - that option requires an admin token.
“Approve Lumos Task” and “Deny Lumos Task” use Lumos’s complete and dismiss endpoints, which resolve a task that has a single action. A task offering several actions must be resolved through Lumos’s perform-action endpoint, which Serval does not model. Run “Get Lumos Task” first to see the actions a task actually offers.
Serval can create and cancel access requests and act on tasks. Other Lumos write operations - creating apps, uploading accounts, editing requestable permissions or pre-approval rules - are not available through the integration.
Lists of users, apps, accounts, groups, AppStore data, access requests, and tasks 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.
Lumos expects a separate expand parameter per field, so a custom workflow can only expand one field per call - passing several comma-joined silently returns no expansion rather than an error. This is why “Get Lumos Access Request” makes a second call when you ask it for custom fields, and why the task workflows expand either assignees or actions but not both.
Need help? Contact support@serval.com for assistance with your Lumos integration.