Sso

Base URL: $BUSINESS_API

The object
{
  "id": "sso_01JD3X8Q7M2N4P5R6S7T8V9W0X",
  "tenant_id": "tenant_alpha",
  "provider_type": "saml",
  "name": "Ana Matsinhe",
  "enabled": true,
  "enforce_sso": true,
  "domain": "example.com",
  "domain_verified_at": "2026-11-19T09:30:00Z",
  "domain_verification_token": "domain verification token",
  "client_id": "cli_2vN4gVlCIL3mAZhMyPpwqjJo2xb",
  "has_client_secret": true,
  "discovery_url": "https://example.org/",
  "idp_entity_id": "idp_2hPeETNAEVNOglhgQf5ygZnS0DT",
  "idp_sso_url": "https://example.org/",
  "idp_slo_url": "https://example.org/",
  "idp_certificate": "idp certificate",
  "sp_entity_id": "spe_2rVeejXkCBdC8Z9ugnDqQhPoKZj",
  "sp_certificate": "sp certificate",
  "default_roles": [
    "default role"
  ],
  "group_role_mappings": [
    {
      "group": "utility-finance",
      "role": "finance"
    }
  ],
  "attribute_mapping": {
    "email": "email",
    "name": "name",
    "groups": "groups"
  },
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Read the tenant's single sign-on connection

Logs

GET /sso

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

200 The connection, or null when none is configured

Errors 401 · 403

Permissions business:team:read · Roles: admin, owner

curl -X GET "$BUSINESS_API/sso" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "id": "sso_01JD3X8Q7M2N4P5R6S7T8V9W0X",
  "tenant_id": "tenant_alpha",
  "provider_type": "saml",
  "name": "Ana Matsinhe",
  "enabled": true,
  "enforce_sso": true,
  "domain": "example.com",
  "domain_verified_at": "2026-11-19T09:30:00Z",
  "domain_verification_token": "domain verification token",
  "client_id": "cli_2vN4gVlCIL3mAZhMyPpwqjJo2xb",
  "has_client_secret": true,
  "discovery_url": "https://example.org/",
  "idp_entity_id": "idp_2hPeETNAEVNOglhgQf5ygZnS0DT",
  "idp_sso_url": "https://example.org/",
  "idp_slo_url": "https://example.org/",
  "idp_certificate": "idp certificate",
  "sp_entity_id": "spe_2rVeejXkCBdC8Z9ugnDqQhPoKZj",
  "sp_certificate": "sp certificate",
  "default_roles": [
    "default role"
  ],
  "group_role_mappings": [
    {
      "group": "utility-finance",
      "role": "finance"
    }
  ],
  "attribute_mapping": {
    "email": "email",
    "name": "name",
    "groups": "groups"
  },
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Create or replace the tenant's single sign-on connection

Logs

PUT /sso

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

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

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.

created_atstring (date-time) · optional

When the connection was created.

updated_atstring (date-time) · optional

When the connection was last changed.

Errors 400 · 401 · 403 · 409

Permissions business:team:manage · Roles: admin, owner

curl -X PUT "$BUSINESS_API/sso" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "provider_type": "saml",
  "name": "Corporate sign-in",
  "enabled": true,
  "enforce_sso": true,
  "domain": "example.com",
  "client_id": "cli_2vN4gVlCIL3mAZhMyPpwqjJo2xb",
  "client_secret": "client secret",
  "discovery_url": "https://login.example.com/.well-known/openid-configuration",
  "idp_entity_id": "idp_2hPeETNAEVNOglhgQf5ygZnS0DT",
  "idp_sso_url": "https://example.org/",
  "idp_slo_url": "https://example.org/",
  "idp_certificate": "idp certificate",
  "sp_entity_id": "spe_2rVeejXkCBdC8Z9ugnDqQhPoKZj",
  "default_roles": [
    "operations"
  ],
  "group_role_mappings": [
    {
      "group": "utility-finance",
      "role": "finance"
    }
  ],
  "attribute_mapping": {
    "email": "email",
    "name": "name",
    "groups": "groups"
  }
}'
Response 200
{
  "id": "sso_01JD3X8Q7M2N4P5R6S7T8V9W0X",
  "tenant_id": "tenant_alpha",
  "provider_type": "saml",
  "name": "Ana Matsinhe",
  "enabled": true,
  "enforce_sso": true,
  "domain": "example.com",
  "domain_verified_at": "2026-11-19T09:30:00Z",
  "domain_verification_token": "domain verification token",
  "client_id": "cli_2vN4gVlCIL3mAZhMyPpwqjJo2xb",
  "has_client_secret": true,
  "discovery_url": "https://example.org/",
  "idp_entity_id": "idp_2hPeETNAEVNOglhgQf5ygZnS0DT",
  "idp_sso_url": "https://example.org/",
  "idp_slo_url": "https://example.org/",
  "idp_certificate": "idp certificate",
  "sp_entity_id": "spe_2rVeejXkCBdC8Z9ugnDqQhPoKZj",
  "sp_certificate": "sp certificate",
  "default_roles": [
    "default role"
  ],
  "group_role_mappings": [
    {
      "group": "utility-finance",
      "role": "finance"
    }
  ],
  "attribute_mapping": {
    "email": "email",
    "name": "name",
    "groups": "groups"
  },
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Remove the tenant's single sign-on connection

Logs

DELETE /sso/{id}

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

Returns

204 Connection removed

Errors 401 · 403

Permissions business:team:manage · Roles: admin, owner

curl -X DELETE "$BUSINESS_API/sso/{id}" \
  -H "Authorization: Bearer sk_test_..."
Response 204

Connection removed

Extract SAML settings from identity provider metadata

Logs

POST /sso/saml/metadata

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

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

idp_certificatestring · required

Signing certificate from the metadata.

Errors 400 · 401 · 403

Permissions business:team:manage · Roles: admin, owner

curl -X POST "$BUSINESS_API/sso/saml/metadata" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "xml": "<EntityDescriptor xmlns=\"urn:oasis:names:tc:SAML:2.0:metadata\" entityID=\"https://idp.example.com/\">...</EntityDescriptor>"
}'
Response 200
{
  "idp_entity_id": "https://idp.example.com/",
  "idp_sso_url": "https://idp.example.com/sso",
  "idp_slo_url": "https://example.org/",
  "idp_certificate": "idp certificate"
}

Probe the configured identity provider

Logs

POST /sso/test

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

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

Errors 401 · 403 · 404

Permissions business:team:manage · Roles: admin, owner

curl -X POST "$BUSINESS_API/sso/test" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "valid": true,
  "provider_type": "saml",
  "domain": "domain",
  "name": "Ana Matsinhe",
  "enabled": true,
  "checks": [
    {
      "name": "domain_verified",
      "passed": true,
      "detail": "detail"
    }
  ]
}

Verify control of the connection's domain

Logs

POST /sso/verify-domain

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

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

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.

created_atstring (date-time) · optional

When the connection was created.

updated_atstring (date-time) · optional

When the connection was last changed.

Errors 400 · 401 · 403 · 404 · 409

Permissions business:team:manage · Roles: admin, owner

curl -X POST "$BUSINESS_API/sso/verify-domain" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "id": "sso_01JD3X8Q7M2N4P5R6S7T8V9W0X",
  "tenant_id": "tenant_alpha",
  "provider_type": "saml",
  "name": "Ana Matsinhe",
  "enabled": true,
  "enforce_sso": true,
  "domain": "example.com",
  "domain_verified_at": "2026-11-19T09:30:00Z",
  "domain_verification_token": "domain verification token",
  "client_id": "cli_2vN4gVlCIL3mAZhMyPpwqjJo2xb",
  "has_client_secret": true,
  "discovery_url": "https://example.org/",
  "idp_entity_id": "idp_2hPeETNAEVNOglhgQf5ygZnS0DT",
  "idp_sso_url": "https://example.org/",
  "idp_slo_url": "https://example.org/",
  "idp_certificate": "idp certificate",
  "sp_entity_id": "spe_2rVeejXkCBdC8Z9ugnDqQhPoKZj",
  "sp_certificate": "sp certificate",
  "default_roles": [
    "default role"
  ],
  "group_role_mappings": [
    {
      "group": "utility-finance",
      "role": "finance"
    }
  ],
  "attribute_mapping": {
    "email": "email",
    "name": "name",
    "groups": "groups"
  },
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}