> This page is for API Reference & Tools.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.moveworks.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.moveworks.com/_mcp/server.

# Software Access Apps

> Create, read and update Software Access Apps through the Moveworks Configuration API: endpoints, fields and examples.

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

| Method  | Path                              | Endpoint reference                                                                                                           |
| ------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `GET`   | `/tool/access-software/apps`      | [List software access apps](/api-reference/configuration-api/access-skills/software-access-apps/list-software-access-apps)   |
| `POST`  | `/tool/access-software/apps`      | [Create software access app](/api-reference/configuration-api/access-skills/software-access-apps/create-software-access-app) |
| `GET`   | `/tool/access-software/apps/{id}` | [Get software access app](/api-reference/configuration-api/access-skills/software-access-apps/get-software-access-app)       |
| `PATCH` | `/tool/access-software/apps/{id}` | [Update software access app](/api-reference/configuration-api/access-skills/software-access-apps/update-software-access-app) |

### Fields

| Field                       | Type                          | Required  | Notes                                                                                                                                                                                                 |
| --------------------------- | ----------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                        | string                        | read-only | Unique identifier of the app, assigned by the server.                                                                                                                                                 |
| `name`                      | string                        | ✅         | Name of the app as users ask for it. Must be unique in the org and cannot be changed after creation.                                                                                                  |
| `in_assistant_enabled`      | boolean                       |           | If 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_dsl`           | string                        |           | DSL rule deciding which users can request this app. Use 'true' to allow all users, 'false' to allow none, or a DSL expression.                                                                        |
| `admins_email_addrs`        | array\<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_provisioning`   | RoleBasedProvisioningConfig   |           | 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.                  |
| `group_based_provisioning`  | GroupBasedProvisioningConfig  |           | Group-based provisioning: membership in a single group grants access. Set exactly one provisioning strategy.                                                                                          |
| `self_service_provisioning` | SelfServiceProvisioningConfig |           | Self-service provisioning: no automated provisioning; the user is shown instructions to get the app themselves. Set exactly one provisioning strategy.                                                |
| `app_links`                 | AppLinks                      |           | Links related to the app that are shown to the user.                                                                                                                                                  |
| `updated_time`              | string                        | read-only | When the configuration was last updated.                                                                                                                                                              |
| `updated_by`                | string                        | read-only | Who last updated the configuration.                                                                                                                                                                   |
| `version`                   | Version                       | ✅         | 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.

| Field          | Type                          | Required | Notes                                                                                                                                                                          |
| -------------- | ----------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `connector_id` | string                        | ✅        | 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). |
| `roles`        | array\<AccessSoftwareAppRole> | ✅        | Roles the user can choose from. If only one role exists, use group-based provisioning instead.                                                                                 |
| `type`         | enum                          | ✅        | What the roles represent. One of ENVIRONMENT, LICENSE, ROLE, VERSION, or UNKNOWN. One of: `ENVIRONMENT`, `LICENSE`, `ROLE`, `VERSION`, `UNKNOWN`.                              |
| `base_config`  | BaseDirectProvisioningConfig  |          | Approval, 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.

| Field          | Type                         | Required | Notes                                                                                                                                              |
| -------------- | ---------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `connector_id` | string                       | ✅        | The connector that contains the group granting access to this app. ID of an existing connector (GET /configurations/v1alpha1/platform/connectors). |
| `external_id`  | string                       | ✅        | External ID of the group that grants access to this app.                                                                                           |
| `base_config`  | BaseDirectProvisioningConfig |          | Approval, 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.

| Field   | Type   | Required | Notes                                                                                                       |
| ------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------- |
| `title` | string |          | High-level title for the self-service instructions, e.g. 'You can download this app from their website'.    |
| `body`  | string |          | Instructions guiding the user to get the app themselves, such as download links or who to contact for help. |

### Example create body

```json
{
  "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"
  }
}
```