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).
Devolve
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.
Corpo application/json
provider_typestring · obrigatório
Protocol of the identity provider (case-insensitive).
um de saml, oidc
namestring · opcional
Display name for the connection.
enabledboolean · opcional
Whether people can sign in through this connection.
enforce_ssoboolean · opcional
When true, password sign-in is refused for addresses in the verified domain.
domainstring · obrigatório
Email domain the connection serves, as a hostname (stored lower-case). Changing the domain resets its verification.
client_idstring · opcional
OIDC client identifier. Required for oidc.
client_secretstring · opcional
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) · opcional
OIDC issuer discovery URL. Required for oidc; must be a public https address.
idp_entity_idstring · opcional
SAML identity provider entity ID. Required for saml.
idp_sso_urlstring (uri) · opcional
SAML single sign-on URL. Required for saml; must be a public https address.
idp_slo_urlstring (uri) · opcional
SAML single logout URL, optional; must be a public https address when set.
idp_certificatestring · opcional
PEM or base64 X.509 signing certificate of the SAML identity provider. Required for saml.
sp_entity_idstring · opcional
Service provider entity ID to present to the identity provider, when it must differ from the default.
default_rolesarray of string · opcional
Roles given to people signing in who match no group mapping. Defaults to ["operations"]; owner is refused.
group_role_mappingsarray of EnterpriseSsoGroupMapping · opcional
Identity provider groups mapped to tenant roles.
Mostrar atributos filhos
groupstring · obrigatório
Group name or identifier as the identity provider sends it. Must not be blank.
rolestring · obrigatório
Tenant role granted to members of the group. The owner role cannot be granted this way.
attribute_mappingobject · opcional
Names of the identity provider attributes or claims to read. Empty values use the protocol defaults.
Mostrar atributos filhos
emailstring · opcional
Attribute or claim holding the email address.
namestring · opcional
Attribute or claim holding the display name.
groupsstring · opcional
Attribute or claim holding group memberships.
Devolve
200The saved connection, without secrets
Mostrar atributos
idstring · opcional
Connection identifier.
tenant_idstring · opcional
Tenant that owns the connection.
provider_typestring · opcional
Protocol of the identity provider.
um de saml, oidc
namestring · opcional
Display name for the connection.
enabledboolean · opcional
Whether people can sign in through this connection.
enforce_ssoboolean · opcional
Whether password sign-in is refused for addresses in the verified domain.
domainstring · opcional
Email domain the connection serves.
domain_verified_atstring (date-time) · opcional
When control of the domain was proven. Absent until verified.
domain_verification_tokenstring · opcional
Token to publish in the DNS TXT record that proves control of the domain.
client_idstring · opcional
OIDC client identifier.
has_client_secretboolean · opcional
Whether an OIDC client secret is stored.
discovery_urlstring · opcional
OIDC issuer discovery URL.
idp_entity_idstring · opcional
SAML identity provider entity ID.
idp_sso_urlstring · opcional
SAML single sign-on URL.
idp_slo_urlstring · opcional
SAML single logout URL.
idp_certificatestring · opcional
SAML identity provider signing certificate.
sp_entity_idstring · opcional
Service provider entity ID.
sp_certificatestring · opcional
Service provider certificate generated for SAML connections, to register with the identity provider.
default_rolesarray of string · opcional
Roles given to people who match no group mapping.
group_role_mappingsarray of EnterpriseSsoGroupMapping · opcional
Identity provider groups mapped to tenant roles.
Mostrar atributos filhos
groupstring · obrigatório
Group name or identifier as the identity provider sends it. Must not be blank.
rolestring · obrigatório
Tenant role granted to members of the group. The owner role cannot be granted this way.
attribute_mappingobject · opcional
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.
Parâmetros
idstring · caminho · obrigatório
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.
Corpo application/json
xmlstring · obrigatório
The metadata XML document as a string, at most 1 MiB, containing an IDPSSODescriptor.
Devolve
200Settings found in the metadata
Mostrar atributos
idp_entity_idstring · obrigatório
Identity provider entity ID.
idp_sso_urlstring · obrigatório
Single sign-on URL.
idp_slo_urlstring · opcional
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.
Devolve
200Check results
Mostrar atributos
validboolean · obrigatório
True when every check passed.
provider_typestring · obrigatório
Protocol of the tested connection.
um de saml, oidc
domainstring · obrigatório
Domain of the tested connection.
namestring · obrigatório
Display name of the tested connection.
enabledboolean · obrigatório
Whether the connection is enabled.
checksarray of EnterpriseSsoTestCheck · obrigatório
Individual checks, starting with domain_verified.
Mostrar atributos filhos
namestring · obrigatório
Check name, for example domain_verified.
passedboolean · obrigatório
Whether the check passed.
detailstring · opcional
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.
Devolve
200The connection with domain_verified_at set
Mostrar atributos
idstring · opcional
Connection identifier.
tenant_idstring · opcional
Tenant that owns the connection.
provider_typestring · opcional
Protocol of the identity provider.
um de saml, oidc
namestring · opcional
Display name for the connection.
enabledboolean · opcional
Whether people can sign in through this connection.
enforce_ssoboolean · opcional
Whether password sign-in is refused for addresses in the verified domain.
domainstring · opcional
Email domain the connection serves.
domain_verified_atstring (date-time) · opcional
When control of the domain was proven. Absent until verified.
domain_verification_tokenstring · opcional
Token to publish in the DNS TXT record that proves control of the domain.
client_idstring · opcional
OIDC client identifier.
has_client_secretboolean · opcional
Whether an OIDC client secret is stored.
discovery_urlstring · opcional
OIDC issuer discovery URL.
idp_entity_idstring · opcional
SAML identity provider entity ID.
idp_sso_urlstring · opcional
SAML single sign-on URL.
idp_slo_urlstring · opcional
SAML single logout URL.
idp_certificatestring · opcional
SAML identity provider signing certificate.
sp_entity_idstring · opcional
Service provider entity ID.
sp_certificatestring · opcional
Service provider certificate generated for SAML connections, to register with the identity provider.
default_rolesarray of string · opcional
Roles given to people who match no group mapping.
group_role_mappingsarray of EnterpriseSsoGroupMapping · opcional
Identity provider groups mapped to tenant roles.
Mostrar atributos filhos
groupstring · obrigatório
Group name or identifier as the identity provider sends it. Must not be blank.
rolestring · obrigatório
Tenant role granted to members of the group. The owner role cannot be granted this way.
attribute_mappingobject · opcional
Names of the identity provider attributes or claims to read. Empty values use the protocol defaults.