Create App
Create a custom app, or connect an integration.
Omit app_class_id, or send custom, to create a custom app — one Lumos has no connector for, whose accounts you maintain yourself. It needs label_override, category_override and description_override. Any other app_class_id instead connects that integration using the credentials in auth; which keys are required varies by integration, so read them from GET /v1/integrations/{app_class_id}/connection-schema rather than hardcoding them. auth, settings and version only apply when connecting an integration.
Either kind of app can be created with its *_override fields, the same ones PATCH /v1/apps/{app_uuid} sets, and they’re stored exactly as sent. label, description, category, logo_url and website_url are read-only: they show the override where one is set and the app’s default otherwise.
Credentials that validate right away connect the app. Its first sync then waits for an admin to review its match rules, and starts from the Lumos UI or from POST /v1/apps/{app_uuid}:sync with skip_first_sync_review: true. Integrations that need browser consent are finished in the Lumos UI instead. The response is the created app either way. Both are marked connection_source=api, so GET /v1/apps?connection_source=api&disconnected=false lists everything you registered here.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
Body of POST /v1/apps: create a custom app, or connect an integration.
Canonical identifier of an integration, e.g. okta.com. On create, an integration's id connects it with auth/settings. Omit it, or send custom, to create a custom app. On update it is optional and, when supplied, must match the app's own integration — a mismatch is rejected with 400.
Credentials for the integration, as a JSON object — all secrets go here. The accepted keys depend on the integration; read them from GET /v1/integrations/{app_class_id}/connection-schema rather than hardcoding them. Some integrations connect in-band from these credentials; others require browser consent and are finished in the Lumos UI — for those, send {}. Missing or wrong-shaped credentials are rejected with 400, and so are credentials the third party rejects. Only applies to integrations. On update this field is required whenever settings or version is sent, because the credential group is replaced rather than merged.
Non-secret configuration for the integration, as a JSON object — e.g. host, region, or tenant / instance URL. The accepted keys vary by integration and some integrations need none. Only applies to integrations.
Optional integration version override. Pins the connection to a specific integration implementation/version instead of the current default; leave unset (null) unless directed otherwise. Only applies to integrations.
The app's display name in your organization, shown as label. Required when creating a custom app, and can't be cleared on one, since a custom app has no default name. On any other app, send null to clear it, so label shows the app's default name. It can't be empty. At most 255 characters.
1 - 255The app's description in your organization, shown as description. Required when creating a custom app, and can't be cleared on one, since a custom app has no default description. On any other app, send null to clear it, so description shows the app's default description. It can't be empty. At most 1,000 characters.
1 - 1000The app's category in your organization, shown as category. Required when creating a custom app, and can't be cleared on one, since a custom app has no default category. On any other app, send null to clear it, so category shows the app's default category. Possible values: 'Accounting & Finance', 'Marketing & Analytics', 'Content & Social Media', 'Sales & Support', 'Design & Creativity', 'IT & Security', 'Developers', 'HR & Learning', 'Office & Legal', 'Communication', 'Collaboration', 'Commerce & Marketplaces', 'Other', 'Internal'
URL of the app's logo in your organization, shown as logo_url. Send null to clear it, so logo_url shows the app's default logo. It can't be empty. At most 2,048 characters.
1 - 2048URL of the app's website in your organization, shown as website_url. Send null to clear it, so website_url shows the app's default website, if it has one. It can't be empty. At most 2,048 characters.
1 - 2048Instructions shown to a requester when they request access to this app. Unlike the override fields, null is ignored here rather than clearing the current value.
511Message sent to the requester when their access request is approved. Applies to a custom app and a connected integration alike.
1 - 511Response
Successful Response
The unique identifier of the app.
The display name of the app.
The catalog identifier of the underlying app (e.g. "github.com"). Custom apps return "custom".
The app-instance identifier distinguishing multiple instances of the same app.
URL of the app logo image.
URL of the app's official website.
The category this app belongs to.
A description of the app.
The lifecycle status of this app. One of discovered, in-review, needs-review, approved, blocklisted, deprecated.
discovered, in-review, needs-review, approved, blocklisted, deprecated Whether this app has been disconnected (its stored credentials removed via POST /v1/apps/{app_uuid}:disconnect). A disconnected app is excluded from GET /v1/apps?disconnected=false; reconnect it by sending credentials to PATCH /v1/apps/{app_uuid}.
The display name set for this app in your organization, exactly as written. label shows it when set. Null when the app uses its default name. A custom app has no default name, so on one this is always the name it shows.
The description set for this app in your organization, exactly as written. description shows it when set. Null when the app uses its default description. A custom app has no default description, so on one this is always the description it shows.
The category set for this app in your organization, exactly as written. category shows it when set. Null when the app uses its default category. A custom app has no default category, so on one this is always the category it shows.
The logo URL set for this app in your organization, exactly as written. logo_url shows it when set. Null when the app uses its default logo.
The website URL set for this app in your organization, exactly as written. website_url shows it when set. Null when the app uses its default website, if any.
Custom message shown to the requester after their access request is approved. Omitted when none is set.
Users and groups that administer this app. Only present when expand=admins is requested.
Response shape for a Workflow.
- Workflow
- WorkflowRef
Response shape for a Workflow.
- Workflow
- WorkflowRef
Response shape for a Workflow.
- Workflow
- WorkflowRef
AppStore membership and settings. Present when the caller has read access to AppStore items. Returns {in_app_store} by default; expand with expand=appstore_settings for the full settings object.
- AppStoreSettingsCompact
- AppStoreSettingsResponse
Custom attributes configured on this app. Only present when expand=custom_attributes is requested.
The state of this app's most recent sync: syncing while one is running, success or failed once it finished. Omitted when no sync result is recorded — the app has never synced, or was disconnected.
syncing, success, failed