multi-router.aidocs

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.

MethodPathDescriptionScope
GET/v1/ssoGet the SSO connection, with its domain verification record and test sign-in URL.sso:read
POST/v1/ssoCreate the connection from domain, provider and oidc. Returns 201. Accepts an Idempotency-Key.sso:write
PATCH/v1/ssoChange the fields sent, including enabled and enforce_sso. Accepts dry_run.sso:write
DELETE/v1/ssoRemove the connection.sso:delete
POST/v1/sso/verify-domainCheck the domain's DNS TXT record and mark the domain verified.sso:write
POST/v1/sso/checkCheck the issuer's discovery document and signing keys.sso:write
FieldType
domainstring, required on create
The email domain that signs in through SSO.
providerstring, required on create
okta, entra, google, ping, jumpcloud, adfs or generic.
oidcobject, required on create
issuer, client_id and client_secret.
allow_subdomainsboolean
Whether the domain's subdomains also sign in through SSO.
jit_provisioningstring
auto or invite.
default_rolestring
member or admin.
new_user_organization_idstring
The organization new people join.
enabledboolean
Whether SSO sign-in is on. PATCH only.
enforce_ssoboolean
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.

Create the connectionbash
curl -X POST https://api.multi-router.ai/v1/sso \
  -H "Authorization: Bearer $MR_API_KEY" \
  -H "Content-Type: application/json" \
  --data @sso-create.json
sso-create.jsonjson
{
  "domain": "example.com",
  "provider": "okta",
  "oidc": { "issuer": "https://example.okta.com", "client_id": "0oa8x…", "client_secret": "…" },
  "jit_provisioning": "invite",
  "default_role": "member"
}
CodeStatusMeaning
invalid_value400A field has an invalid value, such as an unsupported provider or an organization outside the account.
account_scope_required403The key belongs to a named organization.
sso_disabled403SSO is not enabled for this installation.
sso_not_configured404The account has no SSO connection.
sso_exists409The account already has an SSO connection.
domain_claimed409Another account has claimed the domain.
domain_not_verified409The DNS TXT record was not found.
enforcement_not_ready409Enforcement needs a verified domain, a test sign-in and SSO enabled. details.missing lists what is missing.
sso_enforced409A domain change or delete while SSO is enforced. Turn enforcement off first.
scim_connected409A directory connection locks the SSO settings. Disconnect SCIM first.
rate_limited429Too many verify or check calls. Retry after 60 seconds.
dns_unavailable502DNS could not be read. Retry.
InvitesMachine Identity
Was this helpful?