Skip to main content
Setting up an app for self-service access spans five v1 resources: integrations, apps, entitlements, the app’s AppStore settings, and workflows. This guide puts the pieces those pages describe in order. It covers both an app connected through a Lumos integration and a custom app whose accounts you maintain yourself. You can set up a custom app entirely through the API, but connecting an app through an integration also needs the Lumos UI, as steps 1-3 describe.

​
Before you start

Create your API token as a user with the Admin role. A token can do only what the user who created it can do, as What a token is allowed to do describes. Of the built-in roles, only Admin can create or connect apps. App Admin can configure the AppStore for the apps they administer. Run the steps below in order. Before you set default_entitlement or request_validation_webhook_uuid, you must have the entitlement’s or the inline webhook’s ID.

​
Setting up the app

1

Create or connect the app

To connect an app through an integration, find the integration’s app_class_id with List Integrations. Then read the credentials it needs from Get Integration Connection Schema. Its auth_schema describes auth, and its settings_schema describes settings. Send app_class_id, auth, and settings to Create App.
Create App returns 201 with the app. Save its id, because every later step uses it. If Create App returns 422 with code set to app.api_unsupported, the API can’t connect this integration, so connect it in the Lumos UI. Create a custom app or connect an integration lists those integrations, and what to do about an on-prem integration.For an integration that needs browser consent, send auth: {}. Then finish connecting the app in the Lumos UI.To create a custom app, an app that Lumos has no integration for, send label_override, category_override, and description_override to Create App. Don’t send app_class_id. category_override must be a label from List App Categories.
Lumos makes the user who created the token the new app’s admin.
2

Give it accounts and entitlements

An app connected through an integration gets its accounts and entitlements from syncs. Its first sync waits for a review of the app’s identity matching rules. To start it without the review, send skip_first_sync_review: true to Trigger App Sync. To review the rules first, start it from the Lumos UI instead.
Trigger App Sync returns an operation to poll, as Syncs and their status describes. The first sync explains when you must send the flag again.A custom app has no integration, so you supply both. Send its accounts with Upload Accounts. Uploading accounts shows the body. Then add each entitlement people can request with Create Entitlement:
Step 5 shows or hides each entitlement. Creating, updating, and deleting explains which entitlements start visible.
3

Give it an admin and approvers

Check the app’s admins with expand=admins:
A custom app you created already has an admin. For an app connected through an integration, set its admins with Set App Admins. Send the complete list, because it replaces the app’s admins:
The app needs at least one admin before you add it to the AppStore in step 4. Otherwise that call returns 409 with code set to app.admin_required.While the app has no approval workflow bound, Lumos uses the app’s approval settings in the Lumos UI.
By default, requests for a new app need no approval. Before you make the app visible in step 6, do one of these:
The Workflow object explains what a workflow is, and Bound workflows covers the provisioning workflows, which work the same way.
4

Add it to the AppStore, still hidden

Add the app to the AppStore with Update AppStore Settings. Set catalog_visibility to hidden so that requesters don’t see it yet. An entitlement’s AppStore settings exist only while its app is in the AppStore, so add the app before step 5:
A new app’s catalog_visibility is already hidden. If the app was already visible, this call hides it.
5

Configure its entitlements

List the entitlements by visibility with List App Entitlements. Finding entitlements explains the visible_in_appstore filter.Show or hide each one with Update Entitlement AppStore Settings:
For an entitlement without AppStore settings, this call returns 404. To make that access requestable anyway, create a separate entitlement for it with Create Entitlement. AppStore settings on the Entitlement object explains which entitlements have AppStore settings, and lists the other fields.
6

Make it visible

Set catalog_visibility to visible with Update AppStore Settings. You can change other settings in the same call:
AppStore settings on the App object describes every field.
7

Check what a requester sees

Get AppStore Catalog lists the apps one user can request. Get App Entitlement AppStore Catalog lists what they can request on one app. Both results depend on that user’s groups.To see someone else’s catalog, pass their user id from List Users as target_user_uuid. Of the built-in roles, Admin, Read Only Admin, and AppStore Read Only Admin can pass it to both endpoints. App Admin can pass it to the entitlement catalog for the apps they administer. A custom role can also allow it.
A listing without search omits apps whose catalog_visibility is search-only, so search by name when you check a search-only app. The catalog also omits apps whose allowed requester groups don’t include the user.The entitlement catalog returns an empty page, not 404, while the app isn’t in the AppStore or its catalog_visibility is hidden. To see every app in the AppStore, call List Apps with in_app_store=true. Add catalog_visibility (visible, search-only, or hidden) to filter by visibility. Access requests and tasks covers filing a request and following it.

​
Removing an app from the AppStore

Send in_app_store: false to Update AppStore Settings. The app keeps its settings, so sending true again restores it with the same settings. To remove the app from Lumos instead, disconnect or delete it. Creating, updating, disconnecting, and deleting apps explains the difference.