PT EN

Início de sessão único

URL base: $BUSINESS_API

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

Obter a ligação de início de sessão único

Registos

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

Devolve

200 The connection, or null when none is configured

Erros 401 · 403

Permissões business:team:read · Funções: admin, owner

curl -X GET "$BUSINESS_API/sso" \
  -H "Authorization: Bearer sk_test_..."
Resposta 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"
}

Guardar a ligação de início de sessão único

Registos

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.

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

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

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.

created_atstring (date-time) · opcional

When the connection was created.

updated_atstring (date-time) · opcional

When the connection was last changed.

Erros 400 · 401 · 403 · 409

Permissões business:team:manage · Funções: 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"
  }
}'
Resposta 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"
}

Remover a ligação de início de sessão único

Registos

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.

Parâmetros

idstring · caminho · obrigatório

Identifier of the tenant's single sign-on connection (sso_...).

Devolve

204 Connection removed

Erros 401 · 403

Permissões business:team:manage · Funções: admin, owner

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

Connection removed

Ler os metadados SAML de um fornecedor de identidade

Registos

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.

Corpo application/json

xmlstring · obrigatório

The metadata XML document as a string, at most 1 MiB, containing an IDPSSODescriptor.

Devolve

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

idp_certificatestring · obrigatório

Signing certificate from the metadata.

Erros 400 · 401 · 403

Permissões business:team:manage · Funções: 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>"
}'
Resposta 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"
}

Testar a ligação de início de sessão único

Registos

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.

Devolve

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

Erros 401 · 403 · 404

Permissões business:team:manage · Funções: admin, owner

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

Verificar o domínio de início de sessão único

Registos

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.

Devolve

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

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.

created_atstring (date-time) · opcional

When the connection was created.

updated_atstring (date-time) · opcional

When the connection was last changed.

Erros 400 · 401 · 403 · 404 · 409

Permissões business:team:manage · Funções: admin, owner

curl -X POST "$BUSINESS_API/sso/verify-domain" \
  -H "Authorization: Bearer sk_test_..."
Resposta 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"
}