API Reference
SSOEnterprise
Configuring, verifying, checking, enforcing and removing the account's single sign-on connection.
The SSO endpoints manage the account's one OpenID Connect sign-on connection. They need a key of the account organization. The client secret is accepted on create and change, and never returned; reads show only whether it is set. See Setting Up SSO.
| Method | Path | Description | Scope |
|---|---|---|---|
| GET | /v1/sso | Get the SSO connection, with its domain verification record and test sign-in URL. | sso:read |
| POST | /v1/sso | Create the connection from domain, provider and oidc. Returns 201. Accepts an Idempotency-Key. | sso:write |
| PATCH | /v1/sso | Change the fields sent, including enabled and enforce_sso. Accepts dry_run. | sso:write |
| DELETE | /v1/sso | Remove the connection. | sso:delete |
| POST | /v1/sso/verify-domain | Check the domain's DNS TXT record and mark the domain verified. | sso:write |
| POST | /v1/sso/check | Check the issuer's discovery document and signing keys. | sso:write |
| Field | Type |
|---|---|
domain | string, required on create |
| The email domain that signs in through SSO. | |
provider | string, required on create |
| okta, entra, google, ping, jumpcloud, adfs or generic. | |
oidc | object, required on create |
| issuer, client_id and client_secret. | |
allow_subdomains | boolean |
| Whether the domain's subdomains also sign in through SSO. | |
jit_provisioning | string |
| auto or invite. | |
default_role | string |
| member or admin. | |
new_user_organization_id | string |
| The organization new people join. | |
enabled | boolean |
| Whether SSO sign-in is on. PATCH only. | |
enforce_sso | boolean |
| Whether people of the domain must sign in through SSO. PATCH only. | |
Reads add domain_verified, the domain_verification TXT record to publish, scim_connected, last_test_sign_in_at and test_sign_in_url. Setting enforce_sso to true needs a verified domain, a test sign-in and SSO enabled. The verify and check endpoints are rate limited, and return 429 with Retry-After.
| Code | Status | Meaning |
|---|---|---|
invalid_value | 400 | A field has an invalid value, such as an unsupported provider or an organization outside the account. |
account_scope_required | 403 | The key belongs to a named organization. |
sso_disabled | 403 | SSO is not enabled for this installation. |
sso_not_configured | 404 | The account has no SSO connection. |
sso_exists | 409 | The account already has an SSO connection. |
domain_claimed | 409 | Another account has claimed the domain. |
domain_not_verified | 409 | The DNS TXT record was not found. |
enforcement_not_ready | 409 | Enforcement needs a verified domain, a test sign-in and SSO enabled. details.missing lists what is missing. |
sso_enforced | 409 | A domain change or delete while SSO is enforced. Turn enforcement off first. |
scim_connected | 409 | A directory connection locks the SSO settings. Disconnect SCIM first. |
rate_limited | 429 | Too many verify or check calls. Retry after 60 seconds. |
dns_unavailable | 502 | DNS could not be read. Retry. |