Connecting REST Applications with Lumos

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. Lumos does the rest. Think of it as filling out a form about the API. Once the form is right, Lumos can list the app’s users, see who has what access, and even grant or remove access, all 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 tick the box that reveals them:

Tick	To show
Configure Write Capabilities	The seven write configs (assign, unassign, create, update, activate, deactivate, delete)
Show Advanced Authentication Settings	Auth Header Name, Auth Token Prefix, Auth Query Parameter, Second Auth Header Name, OAuth1 Realm, and JWT Claims (JSON)
Configure OAuth 2.0	The OAuth settings
Configure Client Certificate (mTLS)	The mTLS settings

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:

Credential	Use it when
API token or key	The API takes a token or key in a header, or in the web address via Auth Query Parameter
Basic	The API takes a username and password over HTTP Basic, or needs two secret headers (with Second Auth Header Name)
OAuth 2.0 client credentials	Server-to-server OAuth. Set OAuth Token URL
OAuth 2.0 authorization code	OAuth with a user approving access. Set OAuth Authorization URL and OAuth Token URL
OAuth 1.0a	APIs that sign each request (OAuth 1.0a or TBA). Set OAuth1 Realm if the API requires one, like NetSuite
JWT bearer assertion	The API accepts a signed JWT. You provide the JWT headers, claims, and signing secret, and Lumos sends a freshly signed JWT as the bearer token
Key-pair	The API accepts a JWT signed with your private key, like Snowflake. Set JWT Claims (JSON)

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 just structured text made of pairs. A name in quotes, a colon, then a value:

{ "endpoint": "/scim/v2/Users" }

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.

If you want Lumos to…	Fill in
See the app’s users	Accounts Config
See what access exists (roles, groups, licenses)	Entitlements Config
See who holds which access	Associations Config
See workspaces, projects, or other containers	Resources Config
See when each user last logged in	Last Activity Config
Pull extra fields like department or title	Custom Attributes Schema
Grant and remove access, create and disable users	The write configs

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:

[ { "id": "1" }, { "id": "2" } ]

If yours does this, leave records_path out entirely. Most APIs wrap the list inside a named field:

{ "totalResults": 2, "Resources": [ { "id": "1" }, { "id": "2" } ] }

Here the list lives under Resources, so you set "records_path": "Resources". Common wrapper names in the wild: 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": "42",
  "name": { "givenName": "Sarah", "familyName": "Thompson" },
  "emails": [ { "value": "sarah@example.com" } ]
}

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. That’s the whole trick. 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": "none" }

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.

Field	What it is	Example
`offset_param`	The name of the query parameter that carries the starting position	`startIndex` for SCIM, `$skip` for ADP
`size_param`	The parameter that carries how many records per page	`count` for SCIM, `$top` for ADP
`start_offset`	The number the counting starts at. SCIM counts from 1. ADP counts from 0. The default is 0	`1`
`total_path`	Optional. A dotted path to the total record count in the response. When present, Lumos uses it to know when to stop	`totalResults`
`page_size`	How many records to ask for per page. The default is 100	`20`

{ "style": "offset", "offset_param": "startIndex", "size_param": "count", "start_offset": 1, "page_size": 20, "total_path": "totalResults" }

Style: page. You ask for page numbers. “Give me page 3.” Datadog works this way. Lumos stops at the first empty or short page.

Field	What it is	Example
`page_param`	The parameter carrying the page number	`page[number]`
`size_param`	The parameter carrying the page size	`page[size]`
`start_page`	The first page’s number. Usually 1, but Datadog starts at 0. The default is 1	`0`
`page_size`	Records per page. Default 100	`100`

{ "style": "page", "page_param": "page[number]", "size_param": "page[size]", "start_page": 0, "page_size": 100 }

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:

Where the marker appears	Field to set	Example
A token inside the response body, which you send back as a query parameter	`next_cursor_path` for where to read it, plus `cursor_param` for the parameter to send it back in	HubSpot returns `paging.next.after`, echoed back as `?after=`
A complete next-page web address inside the body	`next_url_path`	Salesforce returns `nextRecordsUrl`
A token in a response header	`next_cursor_header`	`X-Next-Token`
A next-page address in the standard `Link` header	`use_link_header: true`	GitHub

size_param and page_size work here too when the API accepts a page-size parameter.

{ "style": "cursor", "next_cursor_path": "paging.next.after", "cursor_param": "after", "size_param": "limit", "page_size": 100 }

Connection settings

The simple fields, before any blocks.

Setting	Default	Plain-English meaning
Base URL	required	The API’s root web address, like `https://api.example.com`. Every endpoint gets added onto this
Auth Header Name	`Authorization`	The name of the header your token travels in. Some vendors use their own, like `X-Api-Key`
Auth Token Prefix	`Bearer`	The word placed before the token. Leave it empty if the API wants the bare key with no prefix
Auth Query Parameter	empty	Only for APIs that want the token in the web address itself, like `?api_key=...`. Setting this switches the token from a header to that parameter
Second Auth Header Name	empty	For APIs needing two secret headers at once. Datadog needs `DD-API-KEY` and `DD-APPLICATION-KEY`. Choose the Basic credential, put the two secrets in its username and password, and name the two headers here and in Auth Header Name
Credential Test Endpoint	empty	A safe path Lumos calls to check the credentials work, like `/scim/v2/Users?count=1`. If empty, Lumos tests against the accounts endpoint
Tenant ID	empty	A stable name for this connection. If empty, Lumos derives one from the Base URL

OAuth settings

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

Setting	Default	Plain-English meaning
OAuth Authorization URL	empty	Where users are sent to click “approve.” Only for the authorization-code flow
OAuth Token URL	empty	Where Lumos trades credentials for an access token. Needed for both OAuth flows
OAuth Extra Authorize Params (JSON)	empty	Extra parameters some vendors require on the approval page. Google needs `{"access_type": "offline", "prompt": "consent"}` or it won’t issue a refresh token
OAuth Client Secret via HTTP Basic	off	Some providers want the client id and secret sent as a Basic login on the token exchange instead of in the request body. Databricks requires this switched on
OAuth Scopes	empty	The permissions to request, space-separated. The connector requests nothing by default, so put whatever the API requires here. Databricks needs `all-apis`
OAuth1 Realm	empty	Only for old OAuth 1.0a APIs, like NetSuite’s account id
JWT Claims (JSON)	empty	Only for the key-pair credential. The claims to sign: `{"iss": "...", "sub": "...", "aud": "...", "algorithm": "RS256", "expiry_minutes": 20}`. `iss` is required, the algorithm defaults to RS256, expiry defaults to 20 minutes, and any extra keys you add become claims too

mTLS settings

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

Setting	Plain-English meaning
Client Certificate (PEM)	The certificate text, pasted in
Client Private Key (PEM)	The matching private key. Both must be set together, and they work with any credential type

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.

Field	Required	What it does
`endpoint`	Yes	The path that lists users
`records_path`	No	Where the list sits in the response. Leave out if the response is the list itself
`pagination`	No	How to get the next page. Defaults to `none`
`mapping`	Yes	Which fields on each user record mean what, detailed below

The mapping translates the API’s field names into Lumos field names. Every field is a dotted path into one user record:

Mapping field	Required	What it points at
`id`	Yes	The user’s unique, permanent identifier. Pick something that never changes
`email`	No	The user’s email address
`given_name`	No	First name
`family_name`	No	Last name
`username`	No	Login name
`status_path`	No	The field that says whether the user is active. Leave out to treat everyone as active
`active_values`	No	The values of that field that count as active. Comparison ignores upper and lower case. The default list is `["active", "enabled", "true", "1", "yes"]`. Values can be written as JSON strings or as bare values like `true` or `1`; Lumos compares them as text

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 hides at workerStatus.statusCode.codeValue with values like Active, point the path there and list ["Active"]. A complete block for a SCIM-shaped API:

{
  "endpoint": "/scim/v2/Users",
  "records_path": "Resources",
  "pagination": { "style": "offset", "offset_param": "startIndex", "size_param": "count", "start_offset": 1, "page_size": 20, "total_path": "totalResults" },
  "mapping": {
    "id": "id",
    "email": "emails[0].value",
    "given_name": "name.givenName",
    "family_name": "name.familyName",
    "username": "userName",
    "status_path": "active",
    "active_values": ["true"]
  }
}

Entitlements Config

Describes how to list the access that exists in the app. Roles, groups, licenses, teams. Whatever the app calls them.

Field	Required	What it does
`endpoint`	Yes	The path that lists them
`records_path`	No	Where the list sits in the response
`pagination`	No	Defaults to `none`
`type`	No	A one-word label for what kind of access this is. Defaults to `entitlement`. The standard vocabulary is `role`, `license`, `group`, `permission`, and `team`
`mapping`	Yes	Field translation, detailed below

Mapping field	Required	What it points at
`id`	Yes	The entitlement’s unique identifier
`label`	Yes	The human-readable name shown in Lumos
`description`	No	A longer description, if the API provides one
`is_assignable`	No	Set to `true` when you also configure the assign and unassign write configs, so Lumos knows this access can be granted

One kind of access:

{
  "endpoint": "/scim/v2/Groups",
  "records_path": "Resources",
  "pagination": { "style": "offset", "offset_param": "startIndex", "size_param": "count", "start_offset": 1, "page_size": 20, "total_path": "totalResults" },
  "type": "group",
  "mapping": { "id": "id", "label": "displayName" }
}

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:

[
  {
    "endpoint": "/services/data/v59.0/query?q=SELECT+Id,Label+FROM+PermissionSet",
    "records_path": "records",
    "pagination": { "style": "cursor", "next_url_path": "nextRecordsUrl" },
    "type": "permission_set",
    "mapping": { "id": "Id", "label": "Label" }
  },
  {
    "endpoint": "/services/data/v59.0/query?q=SELECT+Id,Name+FROM+Group",
    "records_path": "records",
    "pagination": { "style": "cursor", "next_url_path": "nextRecordsUrl" },
    "type": "group",
    "mapping": { "id": "Id", "label": "Name" }
  }
]

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?

Your API offers…	Mode
One endpoint listing every membership, one row each	`endpoint`
A groups listing where each group carries its member list	`endpoint`, plus `members_path`
User records that carry their own access list	`account_attribute`
Only a per-group members endpoint, asked group by group	`entitlement_fanout`
Only a per-user access endpoint, asked user by user	`account_fanout`

Mode: endpoint

Reads a membership listing.

Field	Required	What it does
`mode`	No	`"endpoint"`. This is the default mode
`endpoint`	Yes	The path to the membership listing
`records_path`	No	Where the list sits in the response
`pagination`	No	Defaults to `none`
`entitlement_id_path`	Yes	Dotted path to the access id on each record
`account_id_path`	Yes	Dotted path to the user id. On the record itself, or on each member entry when `members_path` is set
`members_path`	No	Set this when each record is a group carrying a list of members. Lumos then produces one association per member

Without members_path, for a flat listing like Salesforce’s assignment records:

{
  "mode": "endpoint",
  "endpoint": "/services/data/v59.0/query?q=SELECT+AssigneeId,PermissionSetId+FROM+PermissionSetAssignment",
  "records_path": "records",
  "pagination": { "style": "cursor", "next_url_path": "nextRecordsUrl" },
  "account_id_path": "AssigneeId",
  "entitlement_id_path": "PermissionSetId"
}

With members_path, for SCIM Groups where each group carries its members:

{
  "mode": "endpoint",
  "endpoint": "/scim/v2/Groups",
  "records_path": "Resources",
  "pagination": { "style": "offset", "offset_param": "startIndex", "size_param": "count", "start_offset": 1, "page_size": 20, "total_path": "totalResults" },
  "entitlement_id_path": "id",
  "members_path": "members",
  "account_id_path": "value"
}

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 needed, Lumos reads it during the user sync. Requires Accounts Config to be filled in.

Field	Required	What it does
`mode`	Yes	`"account_attribute"`
`account_entitlements_path`	Yes	Dotted path on each user record to its access entries
`attribute_entitlement_id_path`	Only sometimes	When each entry is an object, the path inside it to the access id. Leave out when entries are plain values

Two verified examples showing the difference. SCIM users carry a groups list of objects, so both fields are needed:

{ "mode": "account_attribute", "account_entitlements_path": "groups", "attribute_entitlement_id_path": "value" }

Google Play users carry developerAccountPermissions as a list of plain text values, so the second field is left out:

{ "mode": "account_attribute", "account_entitlements_path": "developerAccountPermissions" }

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.

Field	Required	What it does
`mode`	Yes	`"entitlement_fanout"`
`endpoint`	Yes	A path template containing `{entitlement_id}`, which Lumos fills in per group
`source_entitlement_type`	Yes	Which Entitlements Config block provides the groups to walk. Must equal that block’s `type`
`records_path`	No	Where the member list sits in each response
`account_id_path`	Yes	Dotted path to the user id on each member
`pagination`	No	Applies to each per-group call

The verified Databricks configuration, needed because Databricks’s groups listing leaves out the members:

{
  "mode": "entitlement_fanout",
  "endpoint": "/api/2.0/accounts/YOUR_ACCOUNT_ID/scim/v2/Groups/{entitlement_id}",
  "records_path": "members",
  "source_entitlement_type": "group",
  "account_id_path": "value",
  "pagination": { "style": "none" }
}

Mode: account_fanout

The mirror image. Ask each user individually what access they hold.

Field	Required	What it does
`mode`	Yes	`"account_fanout"`
`endpoint`	Yes	A path template containing `{account_id}`, filled in per user
`records_path`	No	Where the access list sits in each response
`entitlement_id_path`	Yes	Dotted path to the access id on each row
`pagination`	No	Applies to each per-user call

A note on both fan-out modes. They make one API call per group or per user by nature, so a large tenant means many calls. Syncs resume midway rather than starting over if interrupted. 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.

Field	Required	What it does
`endpoint`	Yes	The path that lists them
`records_path`	No	Where the list sits in the response
`pagination`	No	Defaults to `none`
`type`	No	A one-word label like `workspace` or `profile`. Defaults to `resource`
`mapping`	Yes	`id` and `label` are required paths, `description` is optional

{
  "endpoint": "/services/data/v59.0/query?q=SELECT+Id,Name+FROM+Profile",
  "records_path": "records",
  "pagination": { "style": "cursor", "next_url_path": "nextRecordsUrl" },
  "type": "profile",
  "mapping": { "id": "Id", "label": "Name" }
}

Last Activity Config

Describes where to find when each user was last active, usually a last-login time. Powers inactive-account detection in Lumos.

Field	Required	What it does
`endpoint`	Yes	A path whose records carry a per-user timestamp
`records_path`	No	Where the list sits in the response
`pagination`	No	Defaults to `none`
`mapping.account_id`	Yes	Dotted path to the user id on each record
`mapping.happened_at`	Yes	Dotted path to the timestamp
`mapping.event_type`	No	A constant label for the event, defaulting to `last_activity`. Set it to something meaningful like `last_login`
`mapping.event_type_path`	No	Or read the event type from each record instead of using a constant

Records missing an id or timestamp are skipped, so users who never logged in don’t produce broken events.

{
  "endpoint": "/services/data/v59.0/query?q=SELECT+Id,LastLoginDate+FROM+User",
  "records_path": "records",
  "pagination": { "style": "cursor", "next_url_path": "nextRecordsUrl" },
  "mapping": { "account_id": "Id", "happened_at": "LastLoginDate", "event_type": "last_login" }
}

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.

Field	Required	What it does
`name`	Yes	The attribute’s full name. This exact name is what shows up in Lumos, so make it stable and descriptive
`path`	No	Dotted path to the value on each record. With a path set, the value fills in automatically during sync. Leave it out to declare the attribute without populating it
`attribute_type`	No	`string` for text, which is the default, or `user` when the value refers to another user
`customized_type`	No	Which kind of record carries this attribute: `account` (the default), `entitlement`, or `resource`
`description`	No	A note about what the attribute means

The verified Salesforce example, pulling two extra fields off each user:

[
  { "name": "Department", "path": "Department", "attribute_type": "string", "customized_type": "account", "description": "Salesforce User.Department" },
  { "name": "Title", "path": "Title", "attribute_type": "string", "customized_type": "account", "description": "Salesforce User.Title" }
]

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:

Field	Required	What it does
`method`	No	The kind of call: `POST` (the default), `PUT`, `PATCH`, or `DELETE`
`url`	Yes	The path to call, with placeholders in curly brackets that Lumos fills in
`body`	No	The JSON to send, also with placeholders
`response_id_path`	Create only	Where the new user’s id appears in the response. It doesn’t have to be called “id”. Google Play identifies users by email, so its config sets this to `email`

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:

Write config	Placeholders available
Assign Entitlement / Unassign Entitlement	`{account_id}`, `{entitlement_id}`, `{entitlement_type}`, `{resource_id}`, `{resource_type}`
Create Account	`{email}`, `{username}`, `{given_name}`, `{family_name}`, `{user_status}`
Activate / Deactivate / Delete Account	`{account_id}`
Update Account	`{account_id}` or `{id}`, plus the fields being changed

Two useful details. Placeholders in the url are safely encoded for web addresses. And 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:

{
  "method": "PATCH",
  "url": "/scim/v2/Groups/{entitlement_id}",
  "body": {
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [{ "op": "add", "path": "members", "value": [{ "value": "{account_id}" }] }]
  }
}

Removing access uses a filter to pick out the one member to remove, which is the standard SCIM way to do it:

{
  "method": "PATCH",
  "url": "/scim/v2/Groups/{entitlement_id}",
  "body": {
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [{ "op": "remove", "path": "members[value eq \"{account_id}\"]" }]
  }
}

Disabling a user replaces its active field with false, and enabling replaces it with true. Plain-field PATCH. Some APIs skip the envelope and just take the changed fields. Salesforce disables a user with:

{ "method": "PATCH", "url": "/services/data/v59.0/sobjects/User/{account_id}", "body": { "IsActive": false } }

Junction-record POST. Some APIs model a grant as its own object you create. Salesforce grants a permission set by creating an assignment record:

{
  "method": "POST",
  "url": "/services/data/v59.0/sobjects/PermissionSetAssignment",
  "body": { "AssigneeId": "{account_id}", "PermissionSetId": "{entitlement_id}" }
}

Fair warning on this shape: undoing it usually means finding and deleting that record, which needs a lookup first, and that’s beyond what one templated call can do. Bare DELETE. Deletion is usually a call with no body at all:

{ "method": "DELETE", "url": "/scim/v2/Users/{account_id}" }

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. Real cases: 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.

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:

Rule	Reads as	Fields
Match on an error value	”It’s an error when this field says so”	`error_when_path` points at the field, `error_equals` lists the values that mean error, ignoring case
Error field present	”It’s an error when this field holds anything real”	`error_when_present` points at the field. Empty or false values don’t count, so an API that returns `"error": false` on success works untouched
Match on a success value	”It’s only a success when this field says so. Anything else, or nothing at all, is an error”	`success_when_path` points at the field, `success_equals` lists the acceptable values

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.

{ "error_when_path": "status", "error_equals": ["error", "failed"], "message_path": "error.message", "code_path": "error.code" }

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

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 your pagination), and map the user fields (that’s your mapping). 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.

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.

Connect an App

Supported Generics

Webhooks, ITSM, and Manual Tasks

On-Premise Agent

Connector SDK

Managing Integrations

Integration Library

Connecting REST Applications with Lumos

Where you enter the configuration

How configuration works

The building blocks used in every configuration

1. The endpoint

2. The records path

3. Dotted paths

Connection settings

OAuth settings

mTLS settings

Connecting to an API inside your network

Accounts Config

Entitlements Config

Associations Config

Mode: endpoint

Mode: account_attribute

Mode: entitlement_fanout

Mode: account_fanout

Resources Config

Last Activity Config

Custom Attributes Schema

Write configs (provisioning)

The four shapes real APIs take

Error Detection

Putting it together: your first connection

​Where you enter the configuration

​How configuration works

​The building blocks used in every configuration

​1. The endpoint

​2. The records path

​3. Dotted paths

​4. Pagination

​Connection settings

​OAuth settings

​mTLS settings

​Connecting to an API inside your network

​Accounts Config

​Entitlements Config

​Associations Config

​Mode: endpoint

​Mode: account_attribute

​Mode: entitlement_fanout

​Mode: account_fanout

​Resources Config

​Last Activity Config

​Custom Attributes Schema

​Write configs (provisioning)

​The four shapes real APIs take

​Error Detection

​Putting it together: your first connection

Where you enter the configuration

How configuration works

The building blocks used in every configuration

1. The endpoint

2. The records path

3. Dotted paths

4. Pagination

Connection settings

OAuth settings

mTLS settings

Connecting to an API inside your network

Accounts Config

Entitlements Config

Associations Config

Mode: endpoint

Mode: account_attribute

Mode: entitlement_fanout

Mode: account_fanout

Resources Config

Last Activity Config

Custom Attributes Schema

Write configs (provisioning)

The four shapes real APIs take

Error Detection

Putting it together: your first connection