Skip to navigation

Software Access Apps

View as Markdown

tool.access-software.apps

The software catalog. approval_key.custom_key must name an EXISTING named approval workflow. Supported provisioner systems: ACTIVE_DIRECTORY, GSUITE, MS_GRAPH, OKTA, ONELOGIN.

  • Endpoint: /tool/access-software/apps | Methods: GET, PATCH, POST
  • Request shape: fields go at the top level of the JSON body, with no resource wrapper. The item’s id goes in the URL for reads and updates, not in the body.
  • Updates: a JSON merge-patch. Send only the fields you change, plus version: {num, change_description} with the num from your last read. Lists and maps you send replace the stored ones whole.

Endpoints

All paths are relative to https://api.moveworks.ai/configurations/v1alpha1. Each endpoint page lists the request and response schema, an example, and the errors it can return.

MethodPathEndpoint reference
GET/tool/access-software/appsList software access apps
POST/tool/access-software/appsCreate software access app
GET/tool/access-software/apps/{id}Get software access app
PATCH/tool/access-software/apps/{id}Update software access app

Fields

FieldTypeRequiredNotes
idstringread-onlyUnique identifier of the app, assigned by the server.
namestring✅Name of the app as users ask for it. Must be unique in the org and cannot be changed after creation.
in_assistant_enabledbooleanIf true, users can request this app through the AI Assistant. Takes precedence over access_rule_dsl; use the access rule for more granular control.
access_rule_dslstringDSL rule deciding which users can request this app. Use ‘true’ to allow all users, ‘false’ to allow none, or a DSL expression.
admins_email_addrsarray<string>Email addresses of the app admins who can approve access. Required when the approval model includes app admin approval (APP_ADMIN, APP_ADMIN_THEN_MANAGER, or AUTO_APPROVE_FULL_TIME_ELSE_APP_ADMIN).
role_based_provisioningRoleBasedProvisioningConfigRole-based provisioning: the user picks one of two or more roles (licenses, environments, versions) provisioned through your identity system. Set exactly one provisioning strategy.
group_based_provisioningGroupBasedProvisioningConfigGroup-based provisioning: membership in a single group grants access. Set exactly one provisioning strategy.
self_service_provisioningSelfServiceProvisioningConfigSelf-service provisioning: no automated provisioning; the user is shown instructions to get the app themselves. Set exactly one provisioning strategy.
app_linksAppLinksLinks related to the app that are shown to the user.
updated_timestringread-onlyWhen the configuration was last updated.
updated_bystringread-onlyWho last updated the configuration.
versionVersion✅Document version. On update, send back the num from your last read.

Set at most one of role_based_provisioning, group_based_provisioning, self_service_provisioning.

Variants (3, pick one)

role_based_provisioning

Role-based provisioning: the user picks one of two or more roles (licenses, environments, versions) provisioned through your identity system. Set exactly one provisioning strategy.

FieldTypeRequiredNotes
connector_idstring✅The provisioning system connector (e.g. Okta, Azure AD) that contains the groups for this app. ID of an existing connector (GET /configurations/v1alpha1/platform/connectors).
rolesarray<AccessSoftwareAppRole>✅Roles the user can choose from. If only one role exists, use group-based provisioning instead.
typeenum✅What the roles represent. One of ENVIRONMENT, LICENSE, ROLE, VERSION, or UNKNOWN. One of: ENVIRONMENT, LICENSE, ROLE, VERSION, UNKNOWN.
base_configBaseDirectProvisioningConfigApproval, question, and post-provisioning settings for this app.

group_based_provisioning

Group-based provisioning: membership in a single group grants access. Set exactly one provisioning strategy.

FieldTypeRequiredNotes
connector_idstring✅The connector that contains the group granting access to this app. ID of an existing connector (GET /configurations/v1alpha1/platform/connectors).
external_idstring✅External ID of the group that grants access to this app.
base_configBaseDirectProvisioningConfigApproval, question, and post-provisioning settings for this app.

self_service_provisioning

Self-service provisioning: no automated provisioning; the user is shown instructions to get the app themselves. Set exactly one provisioning strategy.

FieldTypeRequiredNotes
titlestringHigh-level title for the self-service instructions, e.g. ‘You can download this app from their website’.
bodystringInstructions guiding the user to get the app themselves, such as download links or who to contact for help.

Example create body

{
"name": "example-name",
"in_assistant_enabled": true,
"access_rule_dsl": "true",
"role_based_provisioning": {
"connector_id": "<connector-uuid>",
"roles": [
{
"canonical_name": "example-name",
"description": "What this is for",
"user_facing_name": "example-name",
"external_id": "<external-id>"
}
],
"type": "ENVIRONMENT",
"base_config": {
"approval_key": {
"built_in_key": "APP_ADMIN"
},
"questions": [
"<string>"
],
"provisioning_disabled": true,
"post_provisioning_messages": {
"title": "Example title",
"body": "<string>"
}
}
},
"version": {
"change_description": "Create software access app"
}
}