Update App
Update an app in place: its domain-specific metadata overrides, its integration credentials, or both.
The metadata fields are merge-patched: an omitted field keeps its current value. The *_override fields are stored exactly as sent and returned as written; send null to clear one, after which the response returns null for it and the matching read-only field (label, description and so on) shows the app’s default. A custom app has no default name, description or category, so those three can’t be cleared on one. request_instructions ignores null and keeps its current value; there is no way to clear it through this endpoint. The overrides apply to your organization’s copy of the app, not to the shared Lumos app catalog. post_approval_message has no default, so null removes it.
The credential fields — auth, settings and version — are one group that is replaced, not merge-patched. Sending any of the three reconnects the integration with exactly what you send and discards any credentials you leave out, so auth is required whenever you send any of them; a partial credential body is rejected with 400 rather than silently erasing credentials. A custom app has no integration, so it refuses all three with 400. A body with none of the three never touches credentials.
On a reconnect the credentials are re-validated and a sync is triggered, so the app either reconnects in-band or waits on browser consent in the Lumos UI. For an app that has never completed a sync, that triggered sync is held for match-rule review the same way a first connect is; POST /v1/apps/{app_uuid}:sync with skip_first_sync_review: true releases it.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
The app's ID, which GET /v1/apps returns as id.
Body
Body of PATCH /v1/apps/{app_uuid}: update metadata overrides and/or rotate credentials.
Metadata fields are merge-patched; auth, settings and version are replaced as one
group. The router checks that group against the app, since only it knows whether the
app is connected to 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. null removes it.
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