Enterprise SSO

6 endpoints

SAML and OIDC single sign-on for enterprise customers.

sso.read

sso.write

Manage SAML and OIDC SSO connections for a sub-organization.

Authenticate with your organization API key. Include subOrgId as a query parameter or in the request body when using an org-wide key. Sub-org-scoped keys automatically target their sub-organization.

GET

/v1/sso/connections

List SSO connections. Requires sso.read.

Query Parameters

Param	Type	Required	Description
subOrgId	string	No	Sub-organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one sub-org.

Response — 200

{ "connections": [ /* SSO connections */ ] }

POST

/v1/sso/connections

Create a SAML or OIDC connection in draft status. Requires sso.write.

Query Parameters

Param	Type	Required	Description
subOrgId	string	No	Sub-organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one sub-org.

Request Body

Param	Type	Required	Description
name	string	Yes	Connection display name
protocol	string	Yes	saml or oidc
idp_entity_id	string	No	SAML IdP entity ID
idp_sso_url	string	No	SAML IdP SSO URL
oidc_issuer	string	No	OIDC issuer URL
oidc_client_id	string	No	OIDC client ID
subOrgId	string	Yes	Sub-organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one sub-org.

Response — 200

{ "connection": { /* draft connection */ } }

GET

/v1/sso/connections/{connectionId}

Get a single SSO connection. Requires sso.read.

Query Parameters

Param	Type	Required	Description
subOrgId	string	No	Sub-organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one sub-org.

Response — 200

{ "connection": { /* ... */ } }

PATCH

/v1/sso/connections/{connectionId}

Update connection configuration, status, or group mappings. Requires sso.write.

Query Parameters

Param	Type	Required	Description
subOrgId	string	No	Sub-organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one sub-org.

Request Body

Param	Type	Required	Description
status	string	No	draft, testing, active, or error
name	string	No	Connection display name
group_role_mapping	object	No	Map IdP groups to OS roles
subOrgId	string	Yes	Sub-organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one sub-org.

Response — 200

{ "connection": { /* updated */ } }

DELETE

/v1/sso/connections/{connectionId}

Delete an SSO connection. Requires sso.write.

Query Parameters

Param	Type	Required	Description
subOrgId	string	No	Sub-organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one sub-org.

Response — 200

{ "success": true }

POST

/v1/sso/connections/{connectionId}/test

Test SAML or OIDC connectivity. Requires sso.write.

Query Parameters

Param	Type	Required	Description
subOrgId	string	No	Sub-organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one sub-org.

Response — 200

{ "success": true, "status": "testing" }