Skip to navigation

SSO

View as Markdown

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.

MethodPathEndpoint reference
GET/platform/sso-connectionsList SSO connections
POST/platform/sso-connectionsCreate SSO connection
GET/platform/sso-connections/{id}Get SSO connection
PATCH/platform/sso-connections/{id}Update SSO connection
DELETE/platform/sso-connections/{id}Delete SSO connection

Fields

FieldTypeRequiredNotes
idstringread-onlyUnique identifier of the SSO configuration, assigned by the server.
productenum✅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_idstringConnector for your identity provider, such as Okta, Microsoft Entra ID or Ping. ID of an existing connector (GET /configurations/v1alpha1/platform/connectors).
identifier_typestringType of identifier used to match users at login: EMAIL_ADDR, ITSM_USER_ID or IDM_USER_ID.
user_attributestringUser attribute that uniquely identifies the user in the identity provider.
saml_configSamlConfigSettings for logging in with SAML.
oidc_configOIDCConfigSettings for logging in with OpenID Connect (OIDC).
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 saml_config, oidc_config.

Variants (2, pick one)

saml_config

Settings for logging in with SAML.

FieldTypeRequiredNotes
urlstring✅Identity provider sign-on (SSO) URL where users are redirected to authenticate.
issuerstringIdentity provider issuer or entity ID that uniquely identifies the identity provider.
disable_authn_requestbooleanIf true, no SAML authentication request is sent. Set to true when the identity provider is Microsoft Graph.
public_certstringIdentity provider public certificate used to verify SAML responses. Secret: always returned masked as *****.
identifier_formatstringSAML 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).

FieldTypeRequiredNotes
redirect_uristring✅Redirect (reply) URL users are sent back to after authenticating with the identity provider, for example https://my.moveworks.com/login/sso/oidc.
issuerstringIdentity provider issuer URL. Must exactly match the issuer in the provider’s OpenID configuration document and must not end with a slash.
client_idstringClient ID issued by your identity provider for the Moveworks application.
client_secretstringClient secret issued by your identity provider for the Moveworks application. Secret: always returned masked as *****.
refresh_auth_cookiebooleanIf true, an already-authenticated user’s token is refreshed instead of repeating the full OIDC authorization flow.
pkce_disabledbooleanIf true, login does not use PKCE (Proof Key for Code Exchange). Not recommended for security reasons.
scopesarray<string>Scopes requested during OIDC authentication. Defaults to openid, email and profile if none are specified.
debug_logging_enabledbooleanIf true, Moveworks records verbose diagnostic logs for the SSO login flow. Enable only while troubleshooting login issues.

Example create body

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