Create App
Create a new custom app, or connect an integration app.
With a name/category/description body this creates a custom app. With an app_class_id body it connects the integration identified by app_class_id using the credentials in auth — integrations that validate in-band connect immediately and trigger an initial sync, while integrations that require browser consent are finished in the Lumos UI. Custom apps and integrations created here are both marked connection_source=API; list your API-managed apps with GET /apps?connection_source=API&disconnected=false.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
Body of POST /apps: create a custom app, or connect an integration.
One flat model serves both operations (a request-body union would generate
poorly into SDK/Terraform clients). Providing app_class_id switches the
request from "create a custom app" to "connect an integration"; the model
validator enforces the fields each mode requires.
The name of the app you're creating. Required when creating a custom app.
The category of the app you're creating; required when creating a custom app. 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'
The description of the app you're creating. Required when creating a custom app.
8192The URL of the logo of the app you're creating.
The URL of the website of the app you're creating.
The request instructions.
Canonical identifier of an integration to connect, e.g. okta.com. Providing it switches this request from creating a custom app to connecting that integration using auth/settings. Must be an integration Lumos supports for your domain; an unknown value is rejected with 400.
Credentials for the integration being connected, as a JSON object — all secrets go here. The accepted keys depend on the integration and are validated server-side. Some integrations connect in-band from these credentials (e.g. an api_key, or an OAuth client_id/client_secret); others require browser consent and are finished in the Lumos UI — for those, send {}. Missing or wrong-shaped credentials are rejected with 400; credentials the third party rejects return 502. Only used with app_class_id.
Non-secret configuration for the integration being connected, as a JSON object — e.g. host, port, region, or tenant / instance URL. The accepted keys vary by integration and some integrations need none. Only used with app_class_id.
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 used with app_class_id.
Response
Successful Response
The ID of this app.
The non-unique ID of the service associated with this requestable permission. Depending on how it is sourced in Lumos, this may be the app's name, website, or other identifier.
The non-unique ID of the instance associated with this app. This will be the Okta app id if it’s an Okta app, or will be marked as custom_app_import if manually uploaded into Lumos.
The user-friendly label of this app.
The status of this app. Possible values: 'DISCOVERED', 'IN_REVIEW', 'NEEDS_REVIEW', 'APPROVED', 'BLOCKLISTED', 'DEPRECATED'
DISCOVERED, IN_REVIEW, NEEDS_REVIEW, APPROVED, BLOCKLISTED, DEPRECATED The sources of this app.
GSUITE_QUICK_INBOX, GSUITE_DEEP_INBOX, MICROSOFT_DEEP_INBOX, MICROSOFT_OAUTH, MICROSOFT_GCC, GSUITE_OAUTH, OKTA, MANUAL, ONELOGIN, ATLASSIAN, GOOGLE_CLOUD, LUMOS_INTEGRATION, JUMPCLOUD, CUSTOM, MCP Determines whether users can request multiple permissions at once.This field will be removed in subsequent API versions.
Whether this app has been disconnected (its stored credentials removed via DELETE /apps/{app_id}). A disconnected app is excluded from GET /apps?disconnected=false; reconnect it with PUT /apps/{app_id}.
A collection of URLs related to this application
The URL of the logo of this app.
The URL of the website of this app.
The request instructions.
The user-facing description of the app
The category of the app, as shown in the AppStore
The state of this app's most recent sync: SYNCING while one is running, SUCCESS or FAILED once it finished. Poll this after POST /apps/{app_id}/sync to follow that sync. null when no sync result is recorded — the app has never synced, or was disconnected.
SYNCING, SUCCESS, FAILED