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:/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 ishttps://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:records_path out entirely.
Most APIs wrap the list inside a named field:
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: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. Thepagination 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.
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:
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:
members_path, for SCIM Groups where each group carries its members:
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:
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 ofentitlement_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: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:
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 nomethod 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 understatic, 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.
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>}.
{ "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.
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.
Putting it together: your first connection
- 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.
- 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.
- 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 yourpagination), and map the user fields (that’s yourmapping). Set the status path and active values last. - Connect. Lumos validates the credentials and the configuration immediately. A configuration mistake shows up here, not silently later.
- 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.