Skip to main content
Connect any REST API to Lumos without writing code. You fill out connection settings that describe the target API: where its data lives, how to log in, and what the responses look like. Once the configuration is complete, Lumos can list the app’s users, see who has what access, and grant or remove access through the API you described. This page explains every setting and every option inside each configuration block. Worked configurations for real APIs (Databricks, ADP, Salesforce, GitHub, Datadog, HubSpot, and more) are on Universal REST Configuration Examples.
The Universal REST connector works for services that do not have complex data models. Examine the configuration guide to determine if the API will be compliant with the Universal REST connector.

Where you enter the configuration

Go to Integrations and click the Generic REST card (or the Generic REST (On Prem) card for an API inside your network). Every setting and block on this page is a field on that card’s connection form, named after the block: the accounts block goes in Accounts Config (JSON), the error rules in Error Detection (JSON), and so on. Some fields are hidden until you select the checkbox that reveals them: Hiding a field only changes what the form displays. It doesn’t clear the value or turn the capability off. You also choose the credential type the connection uses:

How configuration works

The connection has two kinds of settings. Simple fields. Single values you type into a box. The API’s web address, the name of the header your token goes in, and so on. Configuration blocks. Small JSON documents you paste into a box. Each block describes one thing Lumos can do, like “here is how to list this app’s users.” JSON is structured text made of name-value pairs: a name in quotes, a colon, then a value:
That one line says: the list of users lives at the path /scim/v2/Users. Every block on this page follows this same pattern. Names on the left, your values on the right. You only fill in the blocks for what you want. For Lumos to see users without changing anything, fill in the accounts block and stop there. Each block you add unlocks one more capability.

The building blocks used in every configuration

Four ideas repeat in every block. After you learn them, every block below reads the same way.

1. The endpoint

The path where the data lives, added onto your Base URL. If the Base URL is https://api.example.com and the endpoint is /v1/users, Lumos calls https://api.example.com/v1/users. Your API’s documentation lists these paths, usually under names like “List users.”

2. The records path

APIs wrap their lists differently. Some return the list directly:
If yours does this, leave records_path out entirely. Most APIs wrap the list inside a named field:
Here the list lives under Resources, so you set "records_path": "Resources". Common wrapper names: Resources (SCIM), data (Datadog), results (HubSpot), records (Salesforce), workers (ADP), users (Google Play).

3. Dotted paths

Many values sit inside nested fields. A dotted path walks down into them. Given this user record:
The path id reads 42. The path name.givenName walks into name and reads Sarah. The path emails[0].value reads the first entry in the emails list and takes its value, which is the email address. If a field name itself contains dots, wrap it in brackets and quotes: ["urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"].employeeNumber. Every “path” field on this page is one of these.

4. Pagination

APIs return long lists in pages, and each API signals “here is how to get the next page” differently. The pagination object inside each block tells Lumos which signal your API uses. Look at a real response from your API and match it to one of the four styles. Style: none. The API returns everything at once. Nothing else to configure.
Style: offset. You ask for records starting at a position. “Give me 20 records starting at record 21.” SCIM works this way, and so does ADP.
Style: page. You ask for page numbers. “Give me page 3.” Datadog works this way. Lumos stops at the first empty or short page.
Style: cursor. The API hands you a marker for the next page. The marker can arrive four different ways, and you configure exactly one of them: size_param and page_size work here too when the API accepts a page-size parameter.

Connection settings

The simple fields, before any blocks.

OAuth settings

Only needed when your credential is one of the OAuth types.

mTLS settings

Some APIs, like ADP, require a client certificate on every call in addition to the token.

Connecting to an API inside your network

If the API is reachable only from inside your network, use the Generic REST (On Prem) card instead of the cloud card. It runs through the Lumos On-Premise Agent, so set the agent up first (see Installation). The connection settings and configuration blocks on this page are the same for both cards.

Accounts Config

Describes how to list the app’s users. This is the first block to fill in, and the only one required for a basic connection. The mapping translates the API’s field names into Lumos field names. Every field is a dotted path into one user record: How the status works: Lumos reads the field at status_path and checks it against your active_values list. A match means ACTIVE. Anything else means INACTIVE. So for a SCIM API where "active": true, use "status_path": "active" with "active_values": ["true"]. For ADP, where status is at workerStatus.statusCode.codeValue with values like Active, point the path there and list ["Active"]. A complete block for a SCIM-shaped API:

Entitlements Config

Describes how to list the access that exists in the app. Roles, groups, licenses, teams. Whatever the app calls them. One kind of access:
Several kinds of access from one app. Wrap multiple blocks in square brackets to make a list. Each block needs a different type, because other configuration refers to blocks by their type. This verified Salesforce configuration lists permission sets and groups together:

Associations Config

Describes how Lumos learns who holds which access. This is the block with the most options, because APIs expose memberships in four different shapes. Pick the mode matching what your API offers, then fill in that mode’s fields. Which mode do I need?

Mode: endpoint

Reads a membership listing. Without members_path, for a flat listing like Salesforce’s assignment records:
With members_path, for SCIM Groups where each group carries its members:
Reading that second one aloud: list the groups, take each group’s id as the access, look at its members list, and take each member’s value as the user.

Mode: account_attribute

For APIs where each user record already carries its access. No extra endpoint is needed. Lumos reads it during the user sync. Requires Accounts Config to be filled in. Two verified examples showing the difference. SCIM users carry a groups list of objects, so both fields are needed:
Google Play users carry developerAccountPermissions as a list of plain text values, so the second field is left out:

Mode: entitlement_fanout

For APIs with no membership listing at all, where you must ask each group individually who its members are. Lumos walks the entitlements list and calls the endpoint once per entitlement. The verified Databricks configuration, needed because Databricks’s groups listing leaves out the members:

Mode: account_fanout

The reverse of entitlement_fanout. Lumos asks each user individually what access they hold. Both fan-out modes make one API call per group or per user, so a large tenant means many calls. If a sync is interrupted, it resumes midway rather than starting over. Combining sources. Like entitlements, this block accepts a list. Use a list when memberships come from more than one place, such as Salesforce’s permission set assignments plus its group members. The blocks in the list don’t need to use the same mode.

Resources Config

Describes how to list the app’s containers. Workspaces, projects, sites, or profiles. Only needed when access in your app is scoped to a container.

Last Activity Config

Describes where to find when each user was last active, usually a last-login time. Powers inactive-account detection in Lumos. Lumos skips records missing an id or timestamp, so users who never logged in don’t produce broken events.

Custom Attributes Schema

Declares extra fields to pull in beyond the standard ones. Department, title, employee number, cost center. This block is a list, one entry per attribute. The verified Salesforce example, pulling two extra fields off each user:

Write configs (provisioning)

Everything so far reads data. The write configs let Lumos change it. Grant access, remove access, create users, disable users. There are seven, one settings field each, and they all share one shape: A placeholder is a marker like {account_id} that Lumos replaces with the real value when the action runs. Each write config gets its own set: Placeholders in the url are safely encoded for web addresses. A body value that is exactly one placeholder keeps its real type, so a template can produce a true or false rather than the text “true”.

The four shapes real APIs take

The shipped examples establish four patterns. Find the one your API’s documentation matches. SCIM-style PatchOp. Changes are PATCH calls with a standard envelope. Granting access adds a member to the group:
Removing access uses a filter to pick out the one member to remove, which is the standard SCIM way to do it:
Disabling a user replaces its active field with false, and enabling replaces it with true. Plain-field PATCH. Some APIs skip the envelope and take only the changed fields. Salesforce disables a user with:
Junction-record POST. Some APIs model a grant as its own object you create. Salesforce grants a permission set by creating an assignment record:
Undoing this shape usually means finding and deleting that record. That requires a lookup first, which is beyond what one templated call can do. Bare DELETE. Deletion is usually a call with no body at all:
Write configs change the real app Test them against a sandbox before any production system. The SCIM Playground at scim.dev is a free live sandbox built for exactly this, and its configuration on Universal REST Configuration Examples covers the complete write lifecycle.
Where the limit is. Each write config is exactly one API call with values filled in. If an action needs the connector to first look something up, or to compute a value like a timestamp, it can’t be expressed here. Examples include Salesforce permission-set removal and Google Play’s permission updates. Those need a dedicated connector or the Connector SDK, and the Examples page flags each one.

Ticket configs (ITSM)

The ticket configs let Lumos use the app as an ITSM: file a ticket for a request, add comments to it, change its status, and read its status back. Select Configure Ticket Capabilities to show them. After you save the connection, add it as an ITSM connection in Lumos (Connecting Your ITSM) and point your ticket rules at it (Configuring ITSM Rules in Lumos). Only Create Ticket Config is required. Add the others for each step you want Lumos to take on the ticket.

The ticket write configs

Create, comment, and transition use the same shape as the write configs above (method, url, body), plus a few fields for reading the result: Each config gets its own placeholders: A requester or subject placeholder is only filled when Lumos has that value. When a body value is exactly one placeholder and Lumos has no value for it, that key is left out of the request.

Get Ticket Config

A read, not a write, so it has no method or body.

Listing choices: transitions, destination fields, and ticket fields

These three blocks give Lumos a list of choices. Each takes either a fixed list under static, or an endpoint that Lumos reads. Set exactly one. An endpoint has a url and optional records_path, pagination, id_path (default id), and label_path (default name). Add filter to keep only some records, like { "field": "type", "equals": 0 }, for APIs that can’t filter on their own. The URL can use {destination_<key>} to list choices for the destination a rule picked. Ticket Transitions. The statuses a ticket can move to. A static entry is { "id": "...", "name": "..." }. If moving to a status is a separate action with its own id, as in Jira, add to_status_id (or to_status_id_path on an endpoint). With to_status_id_path, Lumos doesn’t know the target status when it changes the ticket, so {to_status_id} is empty in the Transition Ticket call and Lumos can’t check that the ticket actually moved.
Ticket Destination Fields. A list of fields you fill in on each ITSM destination. Each needs a key (letters, digits, and underscores only), a label, and options (a static list or an endpoint). Lumos uses at most two destination fields. When there are two, the one the other depends_on is first, like a project, and the other is second, like a ticket type. Without depends_on, the first field in the list is first. A third field is ignored, and if a third field is required, Lumos can’t use the connection for ITSM. Add "required": true to make one mandatory, and depends_on to scope its options by an earlier field. The value picked fills {destination_<key>}.
Ticket Fields. Extra fields Lumos can fill in. A static entry is { "key": "...", "name": "...", "type": "..." }, where type is text (the default), number, boolean, date, single_select, multi_select, or user. Add "required": true to make one mandatory. Select types take options, a list of { "id": "...", "name": "..." }. An endpoint reads each record’s key from id_path and its name from label_path, and also takes type_path (with type_map to translate the API’s type names; anything unmapped is text), required_path, and options_path with option_id_path (default id) and option_label_path (default name). A user field is sent as the person’s id when Requester Lookup finds one, or else their email.

Requester Lookup

For APIs whose create call takes a user id, not an email. Lumos calls this before creating the ticket and fills {requester_id} and {subject_id} with what it finds.
If no one matches, the ticket is still filed, without the id. A complete working configuration is under Halo ITSM on Universal REST Configuration Examples.

Error Detection

Most APIs report failures with an error status code, and Lumos handles those automatically. A few APIs always say “success” at the HTTP level and hide failures inside the response body. This optional block teaches Lumos to spot them, and it applies to every call the connection makes. Configure exactly one of the three detection rules: Two optional extras work with any rule. message_path points at the API’s human-readable error message, and code_path at its error code, so both appear in Lumos when something fails.
A badly formed block fails immediately when you connect, during the credential check, rather than quietly during a sync later.

Putting it together: your first connection

  1. Get one real response. Ask whoever owns the API for a sample response from its “list users” endpoint, or find one in its documentation. Everything below comes from looking at it.
  2. Fill in the connection settings. The Base URL, and how the token travels (which header, which prefix). The API’s authentication documentation states this on its first page.
  3. Write the Accounts Config. Find the list in the sample response (that’s your records_path), find how the API signals more pages (that’s your pagination), and map the user fields (that’s your mapping). Set the status path and active values last.
  4. Connect. Lumos validates the credentials and the configuration immediately. A configuration mistake shows up here, not silently later.
  5. Add blocks one at a time. Entitlements next, then associations, then the rest as needed. Each one can be added later by editing the connection, so there’s no need to configure everything on day one.
If your API resembles one on Universal REST Configuration Examples, start from that configuration and change the paths. Matching on mechanics beats matching on vendor: an offset-paginated SCIM-ish API can copy the SCIM Playground configuration nearly unchanged, whatever the app is called.