Skip to main content
POST
Create App

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

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.

name
string | null

The name of the app you're creating. Required when creating a custom app.

category
string | null

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'

description
string | null

The description of the app you're creating. Required when creating a custom app.

Maximum string length: 8192
logo_url
string | null

The URL of the logo of the app you're creating.

website_url
string | null

The URL of the website of the app you're creating.

request_instructions
string | null

The request instructions.

app_class_id
string | null

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.

auth
Auth · object | null

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.

settings
Settings · object | null

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.

version
string | null

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

id
string
required

The ID of this app.

app_class_id
string
required

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.

instance_id
string
required

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.

user_friendly_label
string
required

The user-friendly label of this app.

status
enum<string>
required

The status of this app. Possible values: 'DISCOVERED', 'IN_REVIEW', 'NEEDS_REVIEW', 'APPROVED', 'BLOCKLISTED', 'DEPRECATED'

Available options:
DISCOVERED,
IN_REVIEW,
NEEDS_REVIEW,
APPROVED,
BLOCKLISTED,
DEPRECATED
sources
enum<string>[]
required

The sources of this app.

Available options:
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
allow_multiple_permission_selection
boolean
required

Determines whether users can request multiple permissions at once.This field will be removed in subsequent API versions.

disconnected
boolean
required

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

logo_url
string | null

The URL of the logo of this app.

website_url
string | null

The URL of the website of this app.

request_instructions
string | null

The request instructions.

description
string | null

The user-facing description of the app

category
string | null

The category of the app, as shown in the AppStore

sync_status
enum<string> | null

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.

Available options:
SYNCING,
SUCCESS,
FAILED