{"openapi":"3.0.1","info":{"title":"Apps","description":"Manage WorkOS-provisioned machine-to-machine client apps. Standard read operations require all.read or api.apps.read. Write operations and tenant subscription-key retrieval require all.readwrite or api.apps.readwrite.","version":"v4"},"servers":[{"url":"https://talk.perspio.io/apps/v4","description":"AU Region"},{"url":"https://us-talk.perspio.io/apps/v4","description":"US Region"}],"paths":{"/":{"post":{"tags":["App Management"],"summary":"Create App","description":"Create a WorkOS machine-to-machine app. The server generates the app name. If neither access nor the deprecated roles field is supplied, access defaults to all.read with unrestricted security-group access. The plaintext client secret is returned only in this response.","operationId":"createAppV4","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAppRequest"},"example":{"appDescription":"Telemetry analytics service","access":{"accessProfileId":"custom","permissions":{"apps":"readwrite","assets":"read"},"securityGroups":["unrestricted"]}}}}},"responses":{"201":{"description":"The app was created. Store appSecret immediately because it cannot be retrieved again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientApp"},"example":{"appId":"client_01KX54T2AJ20DPEK5D51GQ3B8E","servicePrincipalId":"app_01KX54SZEA70Z3222EJRZ8C8MN","tenantId":"in-tnt-12345678","appName":"api-in-app-2f414330-e111-48e4-9a0c-1344dc63b1de","appDescription":"Telemetry analytics service","appSecretId":"secret_01KX54VD7Y6QR0EPY9M2H9J7AZ","appSecret":"sk_live_new-secret-value","appSecretExpiryDate":null,"subscriptionKey":null,"provisionedVersion":"v4","owners":null,"assetSecurityGroups":[],"isSystemApp":false,"id":"app_01KX54SZEA70Z3222EJRZ8C8MN","type":"ClientAppRecord","correlationId":null,"_ts":0}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"invalid_request","message":"The request is invalid."}}}},"401":{"description":"Missing, invalid, or unauthorized API key or access token"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MiddlewareError"},"example":{"functionName":"Perspio.API.Apps.ClientAppsV4Api","errorType":"InvalidOperationException","statusCode":500,"request":"GET /v4/apps/app_01KX54SZEA70Z3222EJRZ8C8MN","tenantId":"in-tnt-12345678","message":"Internal Server Error: An unexpected error occurred."}}}}}},"get":{"tags":["App Management"],"summary":"Get Apps","description":"Fetch non-system apps provisioned through the v4 WorkOS API. Stored secrets are masked.","operationId":"getAppsV4","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ClientApp"}},"example":[{"appId":"client_01KX54T2AJ20DPEK5D51GQ3B8E","servicePrincipalId":"app_01KX54SZEA70Z3222EJRZ8C8MN","tenantId":"in-tnt-12345678","appName":"api-in-app-2f414330-e111-48e4-9a0c-1344dc63b1de","appDescription":"Telemetry analytics service","appSecretId":"secret_01KX54VD7Y6QR0EPY9M2H9J7AZ","appSecret":"sk**********************","appSecretExpiryDate":null,"subscriptionKey":null,"provisionedVersion":"v4","owners":null,"assetSecurityGroups":[],"isSystemApp":false,"id":"app_01KX54SZEA70Z3222EJRZ8C8MN","type":"ClientAppRecord","correlationId":null,"_ts":0}]}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"invalid_request","message":"The request is invalid."}}}},"401":{"description":"Missing, invalid, or unauthorized API key or access token"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MiddlewareError"},"example":{"functionName":"Perspio.API.Apps.ClientAppsV4Api","errorType":"InvalidOperationException","statusCode":500,"request":"GET /v4/apps/app_01KX54SZEA70Z3222EJRZ8C8MN","tenantId":"in-tnt-12345678","message":"Internal Server Error: An unexpected error occurred."}}}}}}},"/{id}":{"get":{"tags":["App Management"],"summary":"Get App","description":"Fetch a v4 WorkOS app by its WorkOS application id. The stored secret is masked.","operationId":"getappV4","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"app_01KX54SZEA70Z3222EJRZ8C8MN"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientApp"},"example":{"appId":"client_01KX54T2AJ20DPEK5D51GQ3B8E","servicePrincipalId":"app_01KX54SZEA70Z3222EJRZ8C8MN","tenantId":"in-tnt-12345678","appName":"api-in-app-2f414330-e111-48e4-9a0c-1344dc63b1de","appDescription":"Telemetry analytics service","appSecretId":"secret_01KX54VD7Y6QR0EPY9M2H9J7AZ","appSecret":"sk**********************","appSecretExpiryDate":null,"subscriptionKey":null,"provisionedVersion":"v4","owners":null,"assetSecurityGroups":[],"isSystemApp":false,"id":"app_01KX54SZEA70Z3222EJRZ8C8MN","type":"ClientAppRecord","correlationId":null,"_ts":0}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"invalid_request","message":"The request is invalid."}}}},"401":{"description":"Missing, invalid, or unauthorized API key or access token"},"404":{"description":"Client app not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"client_app_not_found","message":"Client app 'app_01KX54SZEA70Z3222EJRZ8C8MN' was not found."}}}},"409":{"description":"The app was provisioned through the legacy API","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"legacy_client_app_endpoint_required","message":"This client app was provisioned via the legacy API; use the legacy endpoints."}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MiddlewareError"},"example":{"functionName":"Perspio.API.Apps.ClientAppsV4Api","errorType":"InvalidOperationException","statusCode":500,"request":"GET /v4/apps/app_01KX54SZEA70Z3222EJRZ8C8MN","tenantId":"in-tnt-12345678","message":"Internal Server Error: An unexpected error occurred."}}}}}},"put":{"tags":["App Management"],"summary":"Update App","description":"Update the name and/or description of a v4 WorkOS app. Set appDescription to null to clear it.","operationId":"updateappV4","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"app_01KX54SZEA70Z3222EJRZ8C8MN"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAppRequest"},"example":{"appName":"Telemetry analytics","appDescription":null}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientApp"},"example":{"appId":"client_01KX54T2AJ20DPEK5D51GQ3B8E","servicePrincipalId":"app_01KX54SZEA70Z3222EJRZ8C8MN","tenantId":"in-tnt-12345678","appName":"Telemetry analytics","appDescription":null,"appSecretId":"secret_01KX54VD7Y6QR0EPY9M2H9J7AZ","appSecret":"sk**********************","appSecretExpiryDate":null,"subscriptionKey":null,"provisionedVersion":"v4","owners":null,"assetSecurityGroups":[],"isSystemApp":false,"id":"app_01KX54SZEA70Z3222EJRZ8C8MN","type":"ClientAppRecord","correlationId":null,"_ts":0}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"invalid_request","message":"The request is invalid."}}}},"401":{"description":"Missing, invalid, or unauthorized API key or access token"},"404":{"description":"Client app not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"client_app_not_found","message":"Client app 'app_01KX54SZEA70Z3222EJRZ8C8MN' was not found."}}}},"409":{"description":"The app was provisioned through the legacy API","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"legacy_client_app_endpoint_required","message":"This client app was provisioned via the legacy API; use the legacy endpoints."}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MiddlewareError"},"example":{"functionName":"Perspio.API.Apps.ClientAppsV4Api","errorType":"InvalidOperationException","statusCode":500,"request":"GET /v4/apps/app_01KX54SZEA70Z3222EJRZ8C8MN","tenantId":"in-tnt-12345678","message":"Internal Server Error: An unexpected error occurred."}}}}}},"delete":{"tags":["App Management"],"summary":"Delete App","description":"Delete a v4 WorkOS app. System apps cannot be deleted.","operationId":"deleteappV4","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"app_01KX54SZEA70Z3222EJRZ8C8MN"}}],"responses":{"204":{"description":"The app was deleted"},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"invalid_request","message":"The request is invalid."}}}},"401":{"description":"Missing, invalid, or unauthorized API key or access token"},"403":{"description":"System apps cannot be deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"system_app_delete_forbidden","message":"System apps cannot be deleted."}}}},"404":{"description":"Client app not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"client_app_not_found","message":"Client app 'app_01KX54SZEA70Z3222EJRZ8C8MN' was not found."}}}},"409":{"description":"The app was provisioned through the legacy API","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"legacy_client_app_endpoint_required","message":"This client app was provisioned via the legacy API; use the legacy endpoints."}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MiddlewareError"},"example":{"functionName":"Perspio.API.Apps.ClientAppsV4Api","errorType":"InvalidOperationException","statusCode":500,"request":"GET /v4/apps/app_01KX54SZEA70Z3222EJRZ8C8MN","tenantId":"in-tnt-12345678","message":"Internal Server Error: An unexpected error occurred."}}}}}}},"/{id}/access":{"get":{"tags":["App Management"],"summary":"Get App Access","description":"Fetch an app's structured access assignment, including canonical security groups.","operationId":"getappaccessV4","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"app_01KX54SZEA70Z3222EJRZ8C8MN"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppAccess"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"invalid_request","message":"The request is invalid."}}}},"401":{"description":"Missing, invalid, or unauthorized API key or access token"},"404":{"description":"Client app or access metadata not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"examples":{"appNotFound":{"value":{"error":"client_app_not_found","message":"Client app 'app_01KX54SZEA70Z3222EJRZ8C8MN' was not found."}},"accessNotFound":{"value":{"error":"client_app_access_not_found","message":"Access metadata for client app 'app_01KX54SZEA70Z3222EJRZ8C8MN' was not found."}}}}}},"409":{"description":"The app was provisioned through the legacy API","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"legacy_client_app_endpoint_required","message":"This client app was provisioned via the legacy API; use the legacy endpoints."}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MiddlewareError"},"example":{"functionName":"Perspio.API.Apps.ClientAppsV4Api","errorType":"InvalidOperationException","statusCode":500,"request":"GET /v4/apps/app_01KX54SZEA70Z3222EJRZ8C8MN","tenantId":"in-tnt-12345678","message":"Internal Server Error: An unexpected error occurred."}}}}}},"put":{"tags":["App Management"],"summary":"Replace App Access","description":"Replace an app's complete access assignment. Omitted permissions or securityGroups are treated as empty collections and clear those assignments. Omitted accessProfileId defaults to api-custom. Use the canonical security-group id unrestricted for unrestricted access.","operationId":"updateappaccessV4","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"app_01KX54SZEA70Z3222EJRZ8C8MN"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessUpdate"},"example":{"accessProfileId":"custom","permissions":{"apps":"readwrite","assets":"read"},"securityGroups":["unrestricted"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppAccess"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"invalid_request","message":"The request is invalid."}}}},"401":{"description":"Missing, invalid, or unauthorized API key or access token"},"404":{"description":"Client app or access metadata not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"examples":{"appNotFound":{"value":{"error":"client_app_not_found","message":"Client app 'app_01KX54SZEA70Z3222EJRZ8C8MN' was not found."}},"accessNotFound":{"value":{"error":"client_app_access_not_found","message":"Access metadata for client app 'app_01KX54SZEA70Z3222EJRZ8C8MN' was not found."}}}}}},"409":{"description":"The app was provisioned through the legacy API","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"legacy_client_app_endpoint_required","message":"This client app was provisioned via the legacy API; use the legacy endpoints."}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MiddlewareError"},"example":{"functionName":"Perspio.API.Apps.ClientAppsV4Api","errorType":"InvalidOperationException","statusCode":500,"request":"GET /v4/apps/app_01KX54SZEA70Z3222EJRZ8C8MN","tenantId":"in-tnt-12345678","message":"Internal Server Error: An unexpected error occurred."}}}}}}},"/{id}/restrictions":{"get":{"tags":["App Management"],"summary":"Get App Restrictions","description":"Get the canonical security-group ids that restrict the app's data access. The value unrestricted represents unrestricted access.","operationId":"getapprestrictionsV4","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"app_01KX54SZEA70Z3222EJRZ8C8MN"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","items":{"type":"string"}},"example":["string"]}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"invalid_request","message":"The request is invalid."}}}},"401":{"description":"Missing, invalid, or unauthorized API key or access token"},"404":{"description":"Client app or access metadata not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"examples":{"appNotFound":{"value":{"error":"client_app_not_found","message":"Client app 'app_01KX54SZEA70Z3222EJRZ8C8MN' was not found."}},"accessNotFound":{"value":{"error":"client_app_access_not_found","message":"Access metadata for client app 'app_01KX54SZEA70Z3222EJRZ8C8MN' was not found."}}}}}},"409":{"description":"The app was provisioned through the legacy API","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"legacy_client_app_endpoint_required","message":"This client app was provisioned via the legacy API; use the legacy endpoints."}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MiddlewareError"},"example":{"functionName":"Perspio.API.Apps.ClientAppsV4Api","errorType":"InvalidOperationException","statusCode":500,"request":"GET /v4/apps/app_01KX54SZEA70Z3222EJRZ8C8MN","tenantId":"in-tnt-12345678","message":"Internal Server Error: An unexpected error occurred."}}}}}},"post":{"tags":["App Management"],"summary":"Update App Restrictions","description":"Replace all security-group restrictions for the app while preserving its permissions and access profile. An empty array clears all security-group access.","operationId":"updateapprestrictionsV4","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"app_01KX54SZEA70Z3222EJRZ8C8MN"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"array","items":{"type":"string"}},"example":["unrestricted"]}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","items":{"type":"string"}},"example":["unrestricted"]}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"invalid_request","message":"The request is invalid."}}}},"401":{"description":"Missing, invalid, or unauthorized API key or access token"},"404":{"description":"Client app or access metadata not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"examples":{"appNotFound":{"value":{"error":"client_app_not_found","message":"Client app 'app_01KX54SZEA70Z3222EJRZ8C8MN' was not found."}},"accessNotFound":{"value":{"error":"client_app_access_not_found","message":"Access metadata for client app 'app_01KX54SZEA70Z3222EJRZ8C8MN' was not found."}}}}}},"409":{"description":"The app was provisioned through the legacy API","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"legacy_client_app_endpoint_required","message":"This client app was provisioned via the legacy API; use the legacy endpoints."}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MiddlewareError"},"example":{"functionName":"Perspio.API.Apps.ClientAppsV4Api","errorType":"InvalidOperationException","statusCode":500,"request":"GET /v4/apps/app_01KX54SZEA70Z3222EJRZ8C8MN","tenantId":"in-tnt-12345678","message":"Internal Server Error: An unexpected error occurred."}}}}}}},"/{id}/subscriptionkey":{"get":{"tags":["App Management"],"summary":"Get App Subscription Key","description":"Fetch the tenant-level APIM subscription keys for the WorkOS external OAuth product. The app id is used to verify that the caller selected an existing v4 app. Because this operation exposes credentials, it requires all.readwrite or api.apps.readwrite.","operationId":"getsubscriptionkeyV4","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"app_01KX54SZEA70Z3222EJRZ8C8MN"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"primaryKey":{"type":"string"},"secondaryKey":{"type":"string"}}},"example":{"primaryKey":"8f2b9c1e-3d48-4a0d-b124-e89f1ab4c7a3","secondaryKey":"a17e5d7f-1b2c-49f3-8f57-7634c3e902b8"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"invalid_request","message":"The request is invalid."}}}},"401":{"description":"Missing, invalid, or unauthorized API key or access token"},"404":{"description":"Client app or tenant WorkOS subscription keys not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"examples":{"appNotFound":{"value":{"error":"client_app_not_found","message":"Client app 'app_01KX54SZEA70Z3222EJRZ8C8MN' was not found."}},"keysNotFound":{"value":{"error":"subscription_keys_not_found","message":"WorkOS external subscription keys were not found for tenant 'in-tnt-12345678'."}}}}}},"409":{"description":"The app was provisioned through the legacy API","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"legacy_client_app_endpoint_required","message":"This client app was provisioned via the legacy API; use the legacy endpoints."}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MiddlewareError"},"example":{"functionName":"Perspio.API.Apps.ClientAppsV4Api","errorType":"InvalidOperationException","statusCode":500,"request":"GET /v4/apps/app_01KX54SZEA70Z3222EJRZ8C8MN","tenantId":"in-tnt-12345678","message":"Internal Server Error: An unexpected error occurred."}}}}}}},"/{id}/users":{"get":{"tags":["App Management"],"summary":"Get App Users","description":"Return users assigned directly to the app. WorkOS v4 apps do not expose direct user assignments, so this operation returns an empty array.","operationId":"getAppUsersV4","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"app_01KX54SZEA70Z3222EJRZ8C8MN"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"maxItems":0,"type":"array","items":{}},"example":[{}]}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"invalid_request","message":"The request is invalid."}}}},"401":{"description":"Missing, invalid, or unauthorized API key or access token"},"404":{"description":"Client app not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"client_app_not_found","message":"Client app 'app_01KX54SZEA70Z3222EJRZ8C8MN' was not found."}}}},"409":{"description":"The app was provisioned through the legacy API","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"legacy_client_app_endpoint_required","message":"This client app was provisioned via the legacy API; use the legacy endpoints."}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MiddlewareError"},"example":{"functionName":"Perspio.API.Apps.ClientAppsV4Api","errorType":"InvalidOperationException","statusCode":500,"request":"GET /v4/apps/app_01KX54SZEA70Z3222EJRZ8C8MN","tenantId":"in-tnt-12345678","message":"Internal Server Error: An unexpected error occurred."}}}}}}},"/{id}/secret":{"post":{"tags":["App Management"],"summary":"Reset App Secret","description":"Rotate an app's client secret. The response contains the new plaintext secret in appSecret. Store it immediately because it cannot be retrieved again.","operationId":"resetAppSecretV4","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"app_01KX54SZEA70Z3222EJRZ8C8MN"}}],"responses":{"200":{"description":"The app secret was reset. Returns the updated app with the new secret value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientApp"},"example":{"appId":"client_01KX54T2AJ20DPEK5D51GQ3B8E","servicePrincipalId":"app_01KX54SZEA70Z3222EJRZ8C8MN","tenantId":"in-tnt-12345678","appName":"api-in-app-2f414330-e111-48e4-9a0c-1344dc63b1de","appDescription":"Telemetry analytics service","appSecretId":"secret_01KX54VD7Y6QR0EPY9M2H9J7AZ","appSecret":"sk_live_new-secret-value","appSecretExpiryDate":null,"subscriptionKey":null,"provisionedVersion":"v4","owners":null,"assetSecurityGroups":[],"isSystemApp":false,"id":"app_01KX54SZEA70Z3222EJRZ8C8MN","type":"ClientAppRecord","correlationId":null,"_ts":0}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"invalid_request","message":"The request is invalid."}}}},"401":{"description":"Missing, invalid, or unauthorized API key or access token"},"404":{"description":"Client app not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"client_app_not_found","message":"Client app 'app_01KX54SZEA70Z3222EJRZ8C8MN' was not found."}}}},"409":{"description":"The app was provisioned through the legacy API","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"example":{"error":"legacy_client_app_endpoint_required","message":"This client app was provisioned via the legacy API; use the legacy endpoints."}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MiddlewareError"},"example":{"functionName":"Perspio.API.Apps.ClientAppsV4Api","errorType":"InvalidOperationException","statusCode":500,"request":"GET /v4/apps/app_01KX54SZEA70Z3222EJRZ8C8MN","tenantId":"in-tnt-12345678","message":"Internal Server Error: An unexpected error occurred."}}}}}}}},"components":{"schemas":{"CreateAppRequest":{"type":"object","properties":{"appDescription":{"type":"string","description":"Optional application description.","nullable":true},"access":{"$ref":"#/components/schemas/AccessUpdate"},"roles":{"allOf":[{"$ref":"#/components/schemas/RolesRequest"}],"description":"Legacy access input. Use access.","deprecated":true},"appName":{"type":"string","description":"Accepted for compatibility but ignored; the server generates the name.","nullable":true,"deprecated":true},"tenantId":{"type":"string","description":"Accepted for compatibility but ignored; the tid header is authoritative.","nullable":true,"deprecated":true},"owners":{"type":"array","items":{"type":"string"},"description":"Accepted for compatibility but not persisted for WorkOS v4 apps.","nullable":true,"deprecated":true}},"additionalProperties":false,"description":"Creation input. access takes precedence when both access and the deprecated roles field are supplied."},"RolesRequest":{"type":"object","properties":{"permissions":{"type":"object","additionalProperties":{"type":"string"}},"assetSecurityGroups":{"type":"array","items":{"type":"string"},"description":"Legacy security-group field. Use access.securityGroups for new clients.","deprecated":true},"profile":{"type":"string","description":"Legacy access-profile name. Values without the api- prefix are normalized to it.","nullable":true}}},"AppAccess":{"type":"object","properties":{"principalId":{"type":"string","format":"uuid"},"accessProfileId":{"type":"string","example":"api-custom"},"hasUnrestrictedAccess":{"type":"boolean"},"permissions":{"type":"array","items":{"type":"string"},"example":["api.apps.readwrite","api.assets.readwrite","api.devices.read"]},"securityGroups":{"type":"array","items":{"$ref":"#/components/schemas/SecurityGroupSummary"}},"modules":{"type":"array","items":{"$ref":"#/components/schemas/AppAccessModule"}},"updatedAt":{"type":"string","format":"date-time"},"accessSource":{"enum":["direct","group","staff","none"],"type":"string"},"editable":{"type":"boolean"},"sources":{"type":"array","items":{"$ref":"#/components/schemas/PrincipalAccessSource"}},"allowedActions":{"type":"array","items":{"type":"string"}}}},"AccessUpdate":{"type":"object","properties":{"accessProfileId":{"type":"string","description":"Replacement access profile. Values without the api- prefix are normalized to it; omission defaults to api-custom.","nullable":true,"example":"custom"},"permissions":{"type":"object","additionalProperties":{"type":"string"},"description":"Replacement permission map. Omission is treated as an empty map and clears permissions.","example":{"apps":"readwrite","assets":"readwrite","devices":"read"}},"securityGroups":{"type":"array","items":{"type":"string"},"description":"Replacement canonical security-group ids. Use unrestricted for unrestricted access. Omission or an explicit empty array clears security-group access.","example":["unrestricted"]}},"additionalProperties":false},"SecurityGroupSummary":{"type":"object","properties":{"id":{"type":"string","example":"unrestricted"},"name":{"type":"string","example":"unrestricted"}}},"PrincipalAccessSource":{"type":"object","properties":{"type":{"type":"string"},"principalId":{"type":"string","format":"uuid","nullable":true},"name":{"type":"string","nullable":true}}},"ClientApp":{"type":"object","properties":{"appId":{"type":"string","description":"WorkOS OAuth client id.","example":"client_01KX54T2AJ20DPEK5D51GQ3B8E"},"servicePrincipalId":{"type":"string","description":"Compatibility identifier; for v4 apps this equals id.","example":"app_01KX54SZEA70Z3222EJRZ8C8MN"},"tenantId":{"type":"string","description":"Owning Perspio tenant id.","example":"in-tnt-12345678"},"appName":{"type":"string","description":"WorkOS application name."},"appDescription":{"type":"string","nullable":true},"appSecretId":{"type":"string","description":"Identifier of the current WorkOS client secret.","nullable":true},"appSecret":{"type":"string","description":"Plaintext only in create and reset responses; masked in stored reads and update responses.","nullable":true},"appSecretExpiryDate":{"type":"string","description":"Always null for current WorkOS client secrets.","format":"date-time","nullable":true},"subscriptionKey":{"type":"string","description":"Legacy compatibility field. Use the subscriptionkey operation to retrieve tenant WorkOS subscription keys.","nullable":true},"provisionedVersion":{"enum":["v4"],"type":"string"},"owners":{"type":"array","items":{"type":"string"},"description":"Legacy compatibility field; newly created v4 apps currently return null.","nullable":true},"assetSecurityGroups":{"type":"array","items":{"type":"string"},"description":"Legacy compatibility field; use the access or restrictions operations."},"isSystemApp":{"type":"boolean"},"id":{"type":"string","description":"WorkOS application id.","example":"app_01KX54SZEA70Z3222EJRZ8C8MN"},"type":{"enum":["ClientAppRecord"],"type":"string"},"correlationId":{"type":"string","nullable":true},"_ts":{"type":"integer","description":"Compatibility timestamp. SQL-backed v4 records currently return zero.","format":"int64"}},"description":"A WorkOS-provisioned machine-to-machine application. Nullable compatibility fields are included in serialized responses."},"UpdateAppRequest":{"type":"object","properties":{"appName":{"minLength":1,"type":"string","description":"New WorkOS application name."},"appDescription":{"type":"string","description":"New description. Use null to clear it.","nullable":true}},"additionalProperties":false},"AppAccessModule":{"type":"object","properties":{"id":{"type":"string"},"enabled":{"type":"boolean"},"canToggle":{"type":"boolean"},"requiredPermissions":{"type":"array","items":{"type":"string"}},"readWrite":{"type":"boolean"},"description":{"type":"string","nullable":true},"subModules":{"type":"array","items":{"$ref":"#/components/schemas/AppAccessModule"}}}},"ApiError":{"required":["error","message"],"type":"object","properties":{"error":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string"}}},"MiddlewareError":{"required":["functionName","errorType","statusCode","message"],"type":"object","properties":{"functionName":{"type":"string"},"errorType":{"type":"string"},"statusCode":{"type":"integer","format":"int32"},"request":{"type":"string","nullable":true},"tenantId":{"type":"string","nullable":true},"message":{"type":"string"}}}},"securitySchemes":{"oauth2":{"type":"oauth2","description":"Client credentials from your Perspio API application. See Get Access Token.","flows":{"clientCredentials":{"tokenUrl":"/auth/v3/token","scopes":{}}}},"subscriptionKey":{"type":"apiKey","name":"Ocp-Apim-Subscription-Key","in":"header","description":"Your tenant's subscription key, from your API application."},"tenantId":{"type":"apiKey","name":"tid","in":"header","description":"Your tenant ID (tid), from your API application."}}},"security":[{"oauth2":[],"subscriptionKey":[],"tenantId":[]}],"tags":[{"name":"App Management","description":"WorkOS client app registration, access, restrictions, subscription keys, and secrets."}],"x-readme":{"oauth-options":{"useInsecureClientAuthentication":true}}}