Returns the caller's tenant SAML or OpenID Connect connection, or a JSON null body with 200 when none is configured. The OIDC client secret and the service provider private key are never returned; has_client_secret reports whether a secret is stored, and domain_verification_token is the value to publish in DNS before verifying the domain. Requires business:team:read (owner and admin roles hold it).
Returns
200The connection, or null when none is configured
Saves the caller's tenant single sign-on settings, creating the connection on first use; a tenant has one connection. provider_type is saml or oidc and domain must be a valid hostname. For oidc, discovery_url and client_id are required, plus client_secret unless one is already stored; for saml, idp_entity_id, idp_sso_url and a valid X.509 idp_certificate are required, and a service provider key pair is generated on first save. URLs must be public https addresses. Roles must be tenant roles and the owner role cannot be granted through federation. Changing the domain clears its verification. client_secret is write-only and is never echoed. Requires business:team:manage; invalid input returns 400 and a domain already claimed by another connection returns 409. The change is recorded in the audit log. Needs a person's session: API keys are refused with 403 and code api_key_not_allowed, whatever scopes they hold.
Body application/json
provider_typestring · required
Protocol of the identity provider (case-insensitive).
one of saml, oidc
namestring · optional
Display name for the connection.
enabledboolean · optional
Whether people can sign in through this connection.
enforce_ssoboolean · optional
When true, password sign-in is refused for addresses in the verified domain.
domainstring · required
Email domain the connection serves, as a hostname (stored lower-case). Changing the domain resets its verification.
client_idstring · optional
OIDC client identifier. Required for oidc.
client_secretstring · optional
OIDC client secret. Write-only: it is encrypted at rest and never returned; reads report has_client_secret instead. Required for oidc unless one is already stored.
discovery_urlstring (uri) · optional
OIDC issuer discovery URL. Required for oidc; must be a public https address.
idp_entity_idstring · optional
SAML identity provider entity ID. Required for saml.
idp_sso_urlstring (uri) · optional
SAML single sign-on URL. Required for saml; must be a public https address.
idp_slo_urlstring (uri) · optional
SAML single logout URL, optional; must be a public https address when set.
idp_certificatestring · optional
PEM or base64 X.509 signing certificate of the SAML identity provider. Required for saml.
sp_entity_idstring · optional
Service provider entity ID to present to the identity provider, when it must differ from the default.
default_rolesarray of string · optional
Roles given to people signing in who match no group mapping. Defaults to ["operations"]; owner is refused.
group_role_mappingsarray of EnterpriseSsoGroupMapping · optional
Identity provider groups mapped to tenant roles.
Show child attributes
groupstring · required
Group name or identifier as the identity provider sends it. Must not be blank.
rolestring · required
Tenant role granted to members of the group. The owner role cannot be granted this way.
attribute_mappingobject · optional
Names of the identity provider attributes or claims to read. Empty values use the protocol defaults.
Show child attributes
emailstring · optional
Attribute or claim holding the email address.
namestring · optional
Attribute or claim holding the display name.
groupsstring · optional
Attribute or claim holding group memberships.
Returns
200The saved connection, without secrets
Show attributes
idstring · optional
Connection identifier.
tenant_idstring · optional
Tenant that owns the connection.
provider_typestring · optional
Protocol of the identity provider.
one of saml, oidc
namestring · optional
Display name for the connection.
enabledboolean · optional
Whether people can sign in through this connection.
enforce_ssoboolean · optional
Whether password sign-in is refused for addresses in the verified domain.
domainstring · optional
Email domain the connection serves.
domain_verified_atstring (date-time) · optional
When control of the domain was proven. Absent until verified.
domain_verification_tokenstring · optional
Token to publish in the DNS TXT record that proves control of the domain.
client_idstring · optional
OIDC client identifier.
has_client_secretboolean · optional
Whether an OIDC client secret is stored.
discovery_urlstring · optional
OIDC issuer discovery URL.
idp_entity_idstring · optional
SAML identity provider entity ID.
idp_sso_urlstring · optional
SAML single sign-on URL.
idp_slo_urlstring · optional
SAML single logout URL.
idp_certificatestring · optional
SAML identity provider signing certificate.
sp_entity_idstring · optional
Service provider entity ID.
sp_certificatestring · optional
Service provider certificate generated for SAML connections, to register with the identity provider.
default_rolesarray of string · optional
Roles given to people who match no group mapping.
group_role_mappingsarray of EnterpriseSsoGroupMapping · optional
Identity provider groups mapped to tenant roles.
Show child attributes
groupstring · required
Group name or identifier as the identity provider sends it. Must not be blank.
rolestring · required
Tenant role granted to members of the group. The owner role cannot be granted this way.
attribute_mappingobject · optional
Names of the identity provider attributes or claims to read. Empty values use the protocol defaults.
Deletes the single sign-on connection with this id from the caller's tenant. The call is idempotent: an id that does not match the tenant's connection still returns 204. Requires business:team:manage. The deletion is recorded in the audit log. Needs a person's session: API keys are refused with 403 and code api_key_not_allowed, whatever scopes they hold.
Parameters
idstring · path · required
Identifier of the tenant's single sign-on connection (sso_...).
Parses a SAML identity provider metadata document and returns the entity ID, single sign-on URL, optional single logout URL and signing certificate, ready to send in a save request. Nothing is stored. A document that is empty, larger than 1 MiB, not well-formed or without an IDPSSODescriptor returns 400. Requires business:team:manage. Needs a person's session: API keys are refused with 403 and code api_key_not_allowed, whatever scopes they hold.
Body application/json
xmlstring · required
The metadata XML document as a string, at most 1 MiB, containing an IDPSSODescriptor.
Returns
200Settings found in the metadata
Show attributes
idp_entity_idstring · required
Identity provider entity ID.
idp_sso_urlstring · required
Single sign-on URL.
idp_slo_urlstring · optional
Single logout URL, when the metadata declares one.
Runs live checks against the caller's tenant identity provider (OIDC discovery, or the SAML endpoints and certificate) and reports each check, starting with whether the domain is verified; valid is true only when all pass. Failed checks are reported in the body with status 200. Takes no request body. Returns 404 when no connection is configured. Requires business:team:manage. Needs a person's session: API keys are refused with 403 and code api_key_not_allowed, whatever scopes they hold.
Returns
200Check results
Show attributes
validboolean · required
True when every check passed.
provider_typestring · required
Protocol of the tested connection.
one of saml, oidc
domainstring · required
Domain of the tested connection.
namestring · required
Display name of the tested connection.
enabledboolean · required
Whether the connection is enabled.
checksarray of EnterpriseSsoTestCheck · required
Individual checks, starting with domain_verified.
Show child attributes
namestring · required
Check name, for example domain_verified.
passedboolean · required
Whether the check passed.
detailstring · optional
Explanation, usually present when the check failed.
Looks up the DNS TXT record for the connection's domain and, when it contains the connection's domain_verification_token, marks the domain verified and claims it for the tenant. Until verified, the domain cannot be enforced or used to route sign-ins or SCIM provisioning. A missing or wrong record returns 400 with a detail naming the record and value to publish; a domain already verified by another tenant returns 409; no connection returns 404. Takes no request body. Requires business:team:manage. The verification is recorded in the audit log. Needs a person's session: API keys are refused with 403 and code api_key_not_allowed, whatever scopes they hold.
Returns
200The connection with domain_verified_at set
Show attributes
idstring · optional
Connection identifier.
tenant_idstring · optional
Tenant that owns the connection.
provider_typestring · optional
Protocol of the identity provider.
one of saml, oidc
namestring · optional
Display name for the connection.
enabledboolean · optional
Whether people can sign in through this connection.
enforce_ssoboolean · optional
Whether password sign-in is refused for addresses in the verified domain.
domainstring · optional
Email domain the connection serves.
domain_verified_atstring (date-time) · optional
When control of the domain was proven. Absent until verified.
domain_verification_tokenstring · optional
Token to publish in the DNS TXT record that proves control of the domain.
client_idstring · optional
OIDC client identifier.
has_client_secretboolean · optional
Whether an OIDC client secret is stored.
discovery_urlstring · optional
OIDC issuer discovery URL.
idp_entity_idstring · optional
SAML identity provider entity ID.
idp_sso_urlstring · optional
SAML single sign-on URL.
idp_slo_urlstring · optional
SAML single logout URL.
idp_certificatestring · optional
SAML identity provider signing certificate.
sp_entity_idstring · optional
Service provider entity ID.
sp_certificatestring · optional
Service provider certificate generated for SAML connections, to register with the identity provider.
default_rolesarray of string · optional
Roles given to people who match no group mapping.
group_role_mappingsarray of EnterpriseSsoGroupMapping · optional
Identity provider groups mapped to tenant roles.
Show child attributes
groupstring · required
Group name or identifier as the identity provider sends it. Must not be blank.
rolestring · required
Tenant role granted to members of the group. The owner role cannot be granted this way.
attribute_mappingobject · optional
Names of the identity provider attributes or claims to read. Empty values use the protocol defaults.