Skip to main content
PATCH
Update App

Authorizations

Authorization
string
header
required

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

Path Parameters

app_uuid
string
required

The app's ID, which GET /v1/apps returns as id.

Body

application/json

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.

app_class_id
string | null

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.

auth
Auth · object | null

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.

settings
Settings · object | null

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.

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 applies to integrations.

label_override
string | null

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.

Required string length: 1 - 255
description_override
string | null

The 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.

Required string length: 1 - 1000
category_override
string | null

The 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'

logo_url_override
string | null

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.

Required string length: 1 - 2048
website_url_override
string | null

URL 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.

Required string length: 1 - 2048
request_instructions
string | null

Instructions 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.

Maximum string length: 511
post_approval_message
string | null

Message sent to the requester when their access request is approved. null removes it.

Required string length: 1 - 511

Response

Successful Response

id
string
required

The unique identifier of the app.

label
string | null

The display name of the app.

app_class_id
string | null

The catalog identifier of the underlying app (e.g. "github.com"). Custom apps return "custom".

instance_id
string | null

The app-instance identifier distinguishing multiple instances of the same app.

logo_url
string | null

URL of the app logo image.

website_url
string | null

URL of the app's official website.

category
string | null

The category this app belongs to.

description
string | null

A description of the app.

status
enum<string> | null

The lifecycle status of this app. One of discovered, in-review, needs-review, approved, blocklisted, deprecated.

Available options:
discovered,
in-review,
needs-review,
approved,
blocklisted,
deprecated
disconnected
boolean
default:false

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}.

label_override
string | null

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.

description_override
string | null

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.

category_override
string | null

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.

logo_url_override
string | null

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.

website_url_override
string | null

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.

post_approval_message
string | null

Custom message shown to the requester after their access request is approved. Omitted when none is set.

admins
AdminAssignee · object[] | null

Users and groups that administer this app. Only present when expand=admins is requested.

approval_workflow
Workflow · object

Response shape for a Workflow.

default_provisioning_workflow
Workflow · object

Response shape for a Workflow.

default_deprovisioning_workflow
Workflow · object

Response shape for a Workflow.

appstore_settings
AppStoreSettingsCompact · object

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.

custom_attributes
Custom Attributes · object | null

Custom attributes configured on this app. Only present when expand=custom_attributes is requested.

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. Omitted when no sync result is recorded — the app has never synced, or was disconnected.

Available options:
syncing,
success,
failed