Create App

post

https://api.lumos.com/apps

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. The connected app is returned; list your API-managed apps with GET /apps?connection_source=API&disconnected=false.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

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

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

category

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

length ≤ 8192

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

logo_url

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

website_url

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

request_instructions

The request instructions.

app_class_id

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

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

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

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.

Responses

400

Bad request — the request could not be processed. Common causes: missing or malformed credentials, an unknown app_class_id, or an invalid configuration value. See the detail field for the specific reason.

403

Forbidden — the caller lacks permission to manage apps on this domain.

409

Conflict — an instance for this app already exists in the domain.

501

Not implemented — this app does not support the requested operation.

502

Bad gateway — the third-party service rejected the credentials, or the post-connect sync failed.

200Successful Response

422Validation Error