> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Lumos

> Lumos is an identity governance and app management platform; Serval connects to it with a Lumos API token to read users, apps, accounts, groups, and AppStore request data on demand in your workflows.

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

These workflows, along with the typed Lumos API request action, cover the read endpoints Serval models from the [Lumos API](https://developers.lumos.com/reference/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](https://developers.lumos.com/docs/quick-start); the [REST API guide](https://developers.lumos.com/docs/rest-api) has more background.

<Steps>
  <Step title="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](https://app.lumosidentity.com/settings/api_tokens).
  </Step>

  <Step title="Create a token">
    Click "Add API Token", enter a name and a description, then click "Create API Token."
  </Step>

  <Step title="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.
  </Step>

  <Step title="Bring the token to Serval">
    Paste the token into the API Token field in Serval's Lumos connect form (next section).
  </Step>
</Steps>

<Warning>
  Lumos shows the token only once, at creation. If you lose it, you cannot view it again - you must create a new token.
</Warning>

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

## Connect in Serval

<Steps>
  <Step title="Open the Lumos connect form">
    In Serval, add the Lumos integration to open its connect form.
  </Step>

  <Step title="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."
  </Step>

  <Step title="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".
  </Step>
</Steps>

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

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

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your Lumos integration.