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

# SSO

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

`platform.sso-connections`

One config per product surface.

* **Endpoint:** `/platform/sso-connections`  |  **Methods:** DELETE, 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`    | `/platform/sso-connections`      | [List SSO connections](/api-reference/configuration-api/platform-org/sso/list-sso-connections)   |
| `POST`   | `/platform/sso-connections`      | [Create SSO connection](/api-reference/configuration-api/platform-org/sso/create-sso-connection) |
| `GET`    | `/platform/sso-connections/{id}` | [Get SSO connection](/api-reference/configuration-api/platform-org/sso/get-sso-connection)       |
| `PATCH`  | `/platform/sso-connections/{id}` | [Update SSO connection](/api-reference/configuration-api/platform-org/sso/update-sso-connection) |
| `DELETE` | `/platform/sso-connections/{id}` | [Delete SSO connection](/api-reference/configuration-api/platform-org/sso/delete-sso-connection) |

### Fields

| Field             | Type       | Required  | Notes                                                                                                                                                                      |
| ----------------- | ---------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`              | string     | read-only | Unique identifier of the SSO configuration, assigned by the server.                                                                                                        |
| `product`         | enum       | ✅         | Moveworks product this SSO configuration is for: my_moveworks or embedded_ai_assistant. Cannot be changed after creation. One of: `embedded_ai_assistant`, `my_moveworks`. |
| `connector_id`    | string     |           | Connector for your identity provider, such as Okta, Microsoft Entra ID or Ping. ID of an existing connector (GET /configurations/v1alpha1/platform/connectors).            |
| `identifier_type` | string     |           | Type of identifier used to match users at login: EMAIL_ADDR, ITSM_USER_ID or IDM_USER_ID.                                                                                  |
| `user_attribute`  | string     |           | User attribute that uniquely identifies the user in the identity provider.                                                                                                 |
| `saml_config`     | SamlConfig |           | Settings for logging in with SAML.                                                                                                                                         |
| `oidc_config`     | OIDCConfig |           | Settings for logging in with OpenID Connect (OIDC).                                                                                                                        |
| `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 `saml_config`, `oidc_config`.

### Variants (2, pick one)

**`saml_config`**

Settings for logging in with SAML.

| Field                   | Type    | Required | Notes                                                                                                                                                             |
| ----------------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `url`                   | string  | ✅        | Identity provider sign-on (SSO) URL where users are redirected to authenticate.                                                                                   |
| `issuer`                | string  |          | Identity provider issuer or entity ID that uniquely identifies the identity provider.                                                                             |
| `disable_authn_request` | boolean |          | If true, no SAML authentication request is sent. Set to true when the identity provider is Microsoft Graph.                                                       |
| `public_cert`           | string  |          | Identity provider public certificate used to verify SAML responses. Secret: always returned masked as \*\*\*\*\*.                                                 |
| `identifier_format`     | string  |          | SAML NameID format for the assertion subject: emailAddress, persistent, transient or unspecified. Leave unset unless your application requires a specific format. |

**`oidc_config`**

Settings for logging in with OpenID Connect (OIDC).

| Field                   | Type           | Required | Notes                                                                                                                                                                                        |
| ----------------------- | -------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `redirect_uri`          | string         | ✅        | Redirect (reply) URL users are sent back to after authenticating with the identity provider, for example [https://my.moveworks.com/login/sso/oidc](https://my.moveworks.com/login/sso/oidc). |
| `issuer`                | string         |          | Identity provider issuer URL. Must exactly match the issuer in the provider's OpenID configuration document and must not end with a slash.                                                   |
| `client_id`             | string         |          | Client ID issued by your identity provider for the Moveworks application.                                                                                                                    |
| `client_secret`         | string         |          | Client secret issued by your identity provider for the Moveworks application. Secret: always returned masked as \*\*\*\*\*.                                                                  |
| `refresh_auth_cookie`   | boolean        |          | If true, an already-authenticated user's token is refreshed instead of repeating the full OIDC authorization flow.                                                                           |
| `pkce_disabled`         | boolean        |          | If true, login does not use PKCE (Proof Key for Code Exchange). Not recommended for security reasons.                                                                                        |
| `scopes`                | array\<string> |          | Scopes requested during OIDC authentication. Defaults to openid, email and profile if none are specified.                                                                                    |
| `debug_logging_enabled` | boolean        |          | If true, Moveworks records verbose diagnostic logs for the SSO login flow. Enable only while troubleshooting login issues.                                                                   |

### Example create body

```json
{
  "product": "embedded_ai_assistant",
  "connector_id": "<connector-uuid>",
  "saml_config": {
    "url": "https://example.com/path",
    "issuer": "<string>",
    "disable_authn_request": true,
    "public_cert": "<PEM certificate>",
    "identifier_format": "emailAddress"
  },
  "version": {
    "change_description": "Create SSO connection"
  }
}
```