Skip to content
DashboardWebsite

Endpoints: SSO & SCIM

Per-organization SSO connections, over OIDC or SAML 2.0, managed by the org’s admins; the public login flow; and the sign-in methods an org accepts. An account is always resolved by the IdP’s identity, (issuer, sub) or (entity id, NameID), never by email. default_role can never be owner: a role granted to anyone the IdP authenticates must not grant full ownership.

OIDC callback — completes an SSO login or link

Public. The IdP redirects the browser here with ?code=&state= after the user authenticates. The callback validates the state, PKCE, nonce and ID token, then finds the account by the IdP’s (issuer, sub), never by email:

  1. An account already linked to this identity signs in.
  2. No account is linked but one has the email: it is not signed in. The browser goes to /login?oauth_error=sso_link_required&sso_org=<org_id>, where the user signs in and links through GET /auth/sso/{org_id}/link. The exception is an account with no password and no linked identity that is already a member of this org, as SCIM creates: it is linked.
  3. No account exists: one is created and linked.

The account joins the org at default_role if it is not a member yet; an existing membership’s role is never lowered. An account with its own TOTP goes to the second-factor step (/login#mfa_token=…). Otherwise the session cookie is set and the browser goes to the dashboard. The session counts as established through an identity provider, so it satisfies the org’s require_2fa policy without TOTP.

Query parameters

NameTypeRequiredDescription
codestringyes
statestringyes
  • 200
  • 307 — Signed in, or sent to the login page to link or to enter a TOTP code
  • 400 — Missing, expired or tampered state, or the code exchange or ID-token check failed
  • 403 — The email’s domain is not in allowed_domains, or the account is deactivated
  • 409 — A link attempt with an IdP account already linked to another account
  • 502 — The identity provider was unreachable

This service provider’s SAML metadata for an org

Public. The SP metadata to give the org’s IdP: entity id, Assertion Consumer Service URL (HTTP-POST binding), and the NameID formats accepted. The entity id is this URL. Served before the org has a connection, so that an IdP can import it first. It says nothing about the org beyond its id.

Path parameters

NameTypeRequiredDescription
org_idstringyes
  • 200
  • 503 — server.public_base_url is not set; SAML needs it

SAML Assertion Consumer Service — receives the IdP’s response

Public. The IdP posts SAMLResponse here (HTTP-POST binding, form-encoded). The API verifies the response: one unencrypted assertion, signed with a configured certificate, from the configured entity id, addressed to this SP, still valid, answering an AuthnRequest, and not used before. It then redirects (303) to GET /auth/sso/saml/complete with a one-time ticket. Nobody is signed in here: only that redirect carries the sso_state cookie that proves which browser started the sign-in. IdP-initiated sign-in (a response that answers no request) is refused.

Path parameters

NameTypeRequiredDescription
org_idstringyes
  • 303 — Verified; continue at /auth/sso/saml/complete
  • 400 — No enabled SAML connection, or the response failed a check; the detail says which
  • 503 — server.public_base_url is not set; SAML needs it

Finish a SAML sign-in in the browser that started it

Public. The ACS redirects here. The ticket works once, for two minutes. The browser’s sso_state cookie must hold the AuthnRequest the response answers; a sign-in started in another browser is refused. The account is then resolved and signed in exactly as GET /auth/sso/callback does for OIDC: by identity, never by email.

Query parameters

NameTypeRequiredDescription
ticketstringyes
  • 200
  • 307 — Signed in, or sent to the login page to link or to enter a TOTP code
  • 400 — Ticket expired or used, missing or expired sso_state, or a response that answers another browser’s request
  • 403 — The email’s domain is not in allowed_domains, or the account is deactivated
  • 409 — A link attempt with an IdP account already linked to another account

Look up which org’s SSO connection an email address belongs to

Public: the caller is not signed in yet. For the login page’s “Continue with SSO” box: matches the email’s domain against every enabled connection’s verified_domains.

Request body (application/json)

{
"email": "string"
}

Response 200 (application/json) — A connection’s verified_domains matched

{
"org_id": "string",
"display_name": "string"
}
  • 404 — No connection matches; fall back to a password login

Start an SSO login for this org

Public. Redirects (307) the browser to the org’s IdP. A short-lived sso_state cookie holds the login attempt: for OIDC the PKCE challenge, nonce and CSRF state; for SAML the AuthnRequest ID.

invite optionally carries an invitation token through the round trip: once signed in, the account joins that org and the session lands there. A dead or mis-addressed invite is ignored and the sign-in completes as usual. When the sign-in continues on the login page (a TOTP step, or an account to link), the token stays in its URL.

Path parameters

NameTypeRequiredDescription
org_idstringyes

Query parameters

NameTypeRequiredDescription
invitestring | nullno
  • 200
  • 307 — Redirect to the IdP
  • 404 — No enabled connection for this org
  • 502 — The identity provider was unreachable
  • 503 — server.public_base_url is not set; SAML needs it

Link the org’s SSO identity to the current account

Requires a signed-in human session. Redirects like GET /auth/sso/{org_id}/start, but the callback attaches the IdP account the user signs in with to this account, then signs it in to the org. This is how an account that existed before the org connected SSO starts using it: the callback never links an account by email.

The account must already be a member of the org; an invitation accepted at sign-in counts. Otherwise the browser goes to /login?oauth_error=sso_link_not_member. A request the browser marks as coming from another site (Sec-Fetch-Site: cross-site) is refused: a link only starts from this deployment’s own pages.

Path parameters

NameTypeRequiredDescription
org_idstringyes
  • 200
  • 307 — Redirect to the IdP, or to the login page when the account is not a member
  • 400 — Called with an API key instead of a session
  • 401 — Not signed in
  • 403 — Started from another site
  • 404 — No enabled connection for this org
  • 502 — The identity provider was unreachable

Get this org’s SSO connection

The org’s SSO connection. Requires the org’s admin role.

Path parameters

NameTypeRequiredDescription
org_idstringyes

Response 200 (application/json)

{
"protocol": "oidc",
"display_name": "string",
"issuer": "string",
"client_id": "string",
"client_secret_set": false,
"idp_entity_id": "string",
"idp_sso_url": "string",
"idp_certificates": [
{
"pem": "string",
"expires_at": "2026-01-01T00:00:00Z"
}
],
"email_attribute": "string",
"service_provider": {
"entity_id": "string",
"acs_url": "string",
"metadata_url": "string"
},
"default_role": "owner",
"allowed_domains": [
"string"
],
"verified_domains": [
"string"
],
"domain_verification_record": "string",
"enabled": true,
"created_at": "2026-01-01T00:00:00Z",
"updated_at": "2026-01-01T00:00:00Z"
}
FieldTypeRequiredDescription
protocol"oidc" | "saml"yes
display_namestringyes
issuerstring | nullnoOIDC only
client_idstring | nullnoOIDC only
client_secret_setbooleannoOIDC only
idp_entity_idstring | nullnoSAML only
idp_sso_urlstring | nullnoSAML only
idp_certificatesSAMLCertificateInfo[]noSAML only
email_attributestring | nullnoSAML only
service_providerSAMLServiceProviderInfo | nullnoSAML only
default_roleOrgRoleyes
allowed_domainsstring[] | nullno
verified_domainsstring[]noThe allowed domains whose DNS proves this org controls them. Only these route sign-ins to this connection.
domain_verification_recordstringyesThe TXT value to publish at _opentremor-challenge. to verify a domain.
enabledbooleanyes
created_atstring (date-time)yes
updated_atstring (date-time)yes
  • 401 — Unauthorized
  • 403 — Forbidden
  • 404 — No connection configured

Connect an OIDC or SAML identity provider (e.g. Entra ID, ADFS) to this org

Connects an identity provider to this org, over OIDC (for example Entra ID) or SAML 2.0 (for example ADFS). Requires the org’s admin role. Its allowed_domains start unverified; POST /orgs/{org_id}/sso/domains/{domain}/verify verifies each one.

OIDC needs issuer, client_id and client_secret. The client secret is encrypted at rest and never returned: responses carry client_secret_set.

SAML needs idp_metadata_xml, or idp_entity_id, idp_sso_url and idp_certificates. The response’s service_provider holds the values to enter in the IdP: entity id, ACS URL and metadata URL.

In the dashboard: Organization → Access → SSO, Single sign-on tab.

Path parameters

NameTypeRequiredDescription
org_idstringyes

Request body (application/json)

{
"protocol": "oidc",
"display_name": "string",
"issuer": "string",
"client_id": "string",
"client_secret": "string",
"idp_entity_id": "string",
"idp_sso_url": "string",
"idp_certificates": [
"string"
],
"idp_metadata_xml": "string",
"email_attribute": "string",
"default_role": "owner",
"allowed_domains": [
"string"
],
"enabled": true
}
FieldTypeRequiredDescription
protocol"oidc" | "saml"noCannot change later: delete the connection and create a new one.
display_namestringyesShown on the login page’s SSO button, e.g. ‘Acme Corp’
issuerstring | nullnoOIDC: issuer URL, e.g. https://login.microsoftonline.com/{tenant}/v2.0
client_idstring | nullnoOIDC: the client id the IdP issued
client_secretstring | nullnoOIDC: encrypted at rest and never returned.
idp_entity_idstring | nullnoSAML: the IdP’s entity id (the assertions’ Issuer)
idp_sso_urlstring | nullnoSAML: the IdP’s sign-in URL for the HTTP-Redirect binding
idp_certificatesstring[] | nullnoSAML: the IdP’s signing certificates, PEM or bare base64. List two to overlap a rotation.
idp_metadata_xmlstring | nullnoSAML only, write only. The IdP’s metadata XML. The API reads idp_entity_id, idp_sso_url and idp_certificates from it; a field also given explicitly wins.
email_attributestring | nullnoSAML: the attribute that carries the email. Unset: NameID when its format is an email address, else the usual email attributes.
default_roleOrgRolenoRole granted to a user auto-provisioned on their first SSO login. Cannot be ‘owner’.
allowed_domainsstring[] | nullnoOptional email-domain allowlist (e.g. [‘acme.com’]). If set, login is rejected for any asserted email outside these domains. Once verified, a domain also routes sign-ins to this connection and blocks other sign-in methods for its addresses (POST /orgs/{org_id}/sso/domains/{domain}/verify).
enabledbooleanno

Response 201 (application/json)

{
"protocol": "oidc",
"display_name": "string",
"issuer": "string",
"client_id": "string",
"client_secret_set": false,
"idp_entity_id": "string",
"idp_sso_url": "string",
"idp_certificates": [
{
"pem": "string",
"expires_at": "2026-01-01T00:00:00Z"
}
],
"email_attribute": "string",
"service_provider": {
"entity_id": "string",
"acs_url": "string",
"metadata_url": "string"
},
"default_role": "owner",
"allowed_domains": [
"string"
],
"verified_domains": [
"string"
],
"domain_verification_record": "string",
"enabled": true,
"created_at": "2026-01-01T00:00:00Z",
"updated_at": "2026-01-01T00:00:00Z"
}
FieldTypeRequiredDescription
protocol"oidc" | "saml"yes
display_namestringyes
issuerstring | nullnoOIDC only
client_idstring | nullnoOIDC only
client_secret_setbooleannoOIDC only
idp_entity_idstring | nullnoSAML only
idp_sso_urlstring | nullnoSAML only
idp_certificatesSAMLCertificateInfo[]noSAML only
email_attributestring | nullnoSAML only
service_providerSAMLServiceProviderInfo | nullnoSAML only
default_roleOrgRoleyes
allowed_domainsstring[] | nullno
verified_domainsstring[]noThe allowed domains whose DNS proves this org controls them. Only these route sign-ins to this connection.
domain_verification_recordstringyesThe TXT value to publish at _opentremor-challenge. to verify a domain.
enabledbooleanyes
created_atstring (date-time)yes
updated_atstring (date-time)yes
  • 401 — Unauthorized
  • 403 — Forbidden
  • 409 — A connection already exists; PATCH it, or DELETE it before creating a new one
  • 503 — server.public_base_url is not set; SAML needs it

Update this org’s SSO connection

All fields optional. Requires the org’s admin role. client_secret replaces the stored secret only when given, so display_name, default_role, allowed_domains and enabled change without re-entering it. Removing a domain from allowed_domains drops its verification.

The protocol cannot change: delete the connection and create a new one. The other protocol’s fields are refused. On a SAML connection, idp_metadata_xml replaces the entity id, sign-in URL and certificates it contains. Changing the entity id (like an OIDC issuer) drops every account link made through the old one.

Path parameters

NameTypeRequiredDescription
org_idstringyes

Request body (application/json)

{
"display_name": "string",
"issuer": "string",
"client_id": "string",
"client_secret": "string",
"idp_entity_id": "string",
"idp_sso_url": "string",
"idp_certificates": [
"string"
],
"idp_metadata_xml": "string",
"email_attribute": "string",
"default_role": "owner",
"allowed_domains": [
"string"
],
"enabled": true
}
FieldTypeRequiredDescription
display_namestring | nullno
issuerstring | nullno
client_idstring | nullno
client_secretstring | nullno
idp_entity_idstring | nullno
idp_sso_urlstring | nullno
idp_certificatesstring[] | nullno
idp_metadata_xmlstring | nullnoSAML only, write only. The IdP’s metadata XML. The API reads idp_entity_id, idp_sso_url and idp_certificates from it; a field also given explicitly wins.
email_attributestring | nullno
default_roleOrgRole | nullno
allowed_domainsstring[] | nullnoOptional email-domain allowlist (e.g. [‘acme.com’]). If set, login is rejected for any asserted email outside these domains. Once verified, a domain also routes sign-ins to this connection and blocks other sign-in methods for its addresses (POST /orgs/{org_id}/sso/domains/{domain}/verify).
enabledboolean | nullno

Response 200 (application/json)

{
"protocol": "oidc",
"display_name": "string",
"issuer": "string",
"client_id": "string",
"client_secret_set": false,
"idp_entity_id": "string",
"idp_sso_url": "string",
"idp_certificates": [
{
"pem": "string",
"expires_at": "2026-01-01T00:00:00Z"
}
],
"email_attribute": "string",
"service_provider": {
"entity_id": "string",
"acs_url": "string",
"metadata_url": "string"
},
"default_role": "owner",
"allowed_domains": [
"string"
],
"verified_domains": [
"string"
],
"domain_verification_record": "string",
"enabled": true,
"created_at": "2026-01-01T00:00:00Z",
"updated_at": "2026-01-01T00:00:00Z"
}
FieldTypeRequiredDescription
protocol"oidc" | "saml"yes
display_namestringyes
issuerstring | nullnoOIDC only
client_idstring | nullnoOIDC only
client_secret_setbooleannoOIDC only
idp_entity_idstring | nullnoSAML only
idp_sso_urlstring | nullnoSAML only
idp_certificatesSAMLCertificateInfo[]noSAML only
email_attributestring | nullnoSAML only
service_providerSAMLServiceProviderInfo | nullnoSAML only
default_roleOrgRoleyes
allowed_domainsstring[] | nullno
verified_domainsstring[]noThe allowed domains whose DNS proves this org controls them. Only these route sign-ins to this connection.
domain_verification_recordstringyesThe TXT value to publish at _opentremor-challenge. to verify a domain.
enabledbooleanyes
created_atstring (date-time)yes
updated_atstring (date-time)yes
  • 401 — Unauthorized
  • 403 — Forbidden
  • 404 — No connection configured
  • 409 — Conflict

Disconnect this org’s SSO connection

Disconnects the org’s SSO connection. Users and memberships stay. Requires the org’s admin role.

Path parameters

NameTypeRequiredDescription
org_idstringyes

Response 200 (application/json)

{
"detail": "string"
}
  • 401 — Unauthorized
  • 403 — Forbidden
  • 404 — No connection configured

POST /v1/orgs/{org_id}/sso/domains/{domain}/verify

Section titled “POST /v1/orgs/{org_id}/sso/domains/{domain}/verify”

Verify that this org controls one of its SSO connection’s allowed domains

Proves this org controls one of its connection’s allowed_domains. Requires the org’s admin role. Looks up the TXT records at _opentremor-challenge.<domain> and expects the connection’s domain_verification_record among them. On success the domain joins verified_domains: it routes sign-ins to this connection, and no other organization can verify it.

Path parameters

NameTypeRequiredDescription
org_idstringyes
domainstringyes

Response 200 (application/json) — Verified, or already verified; returns the connection

{
"protocol": "oidc",
"display_name": "string",
"issuer": "string",
"client_id": "string",
"client_secret_set": false,
"idp_entity_id": "string",
"idp_sso_url": "string",
"idp_certificates": [
{
"pem": "string",
"expires_at": "2026-01-01T00:00:00Z"
}
],
"email_attribute": "string",
"service_provider": {
"entity_id": "string",
"acs_url": "string",
"metadata_url": "string"
},
"default_role": "owner",
"allowed_domains": [
"string"
],
"verified_domains": [
"string"
],
"domain_verification_record": "string",
"enabled": true,
"created_at": "2026-01-01T00:00:00Z",
"updated_at": "2026-01-01T00:00:00Z"
}
FieldTypeRequiredDescription
protocol"oidc" | "saml"yes
display_namestringyes
issuerstring | nullnoOIDC only
client_idstring | nullnoOIDC only
client_secret_setbooleannoOIDC only
idp_entity_idstring | nullnoSAML only
idp_sso_urlstring | nullnoSAML only
idp_certificatesSAMLCertificateInfo[]noSAML only
email_attributestring | nullnoSAML only
service_providerSAMLServiceProviderInfo | nullnoSAML only
default_roleOrgRoleyes
allowed_domainsstring[] | nullno
verified_domainsstring[]noThe allowed domains whose DNS proves this org controls them. Only these route sign-ins to this connection.
domain_verification_recordstringyesThe TXT value to publish at _opentremor-challenge. to verify a domain.
enabledbooleanyes
created_atstring (date-time)yes
updated_atstring (date-time)yes
  • 401 — Unauthorized
  • 403 — Forbidden
  • 404 — No connection configured, or the domain is not in allowed_domains
  • 409 — Another organization has already verified this domain

GET /v1/orgs/{org_id}/sso/service-provider

Section titled “GET /v1/orgs/{org_id}/sso/service-provider”

The SAML service provider values to enter in this org’s IdP

The SP entity id, ACS URL and metadata URL for this org. Requires the org’s admin role. They do not depend on a connection: an IdP needs them before it issues the metadata a SAML connection is created from.

Path parameters

NameTypeRequiredDescription
org_idstringyes

Response 200 (application/json)

{
"entity_id": "string",
"acs_url": "string",
"metadata_url": "string"
}
FieldTypeRequiredDescription
entity_idstringyesThe SP entity id, also the URL of its metadata
acs_urlstringyesAssertion Consumer Service URL, HTTP-POST binding
metadata_urlstringyes
  • 401 — Unauthorized
  • 403 — Forbidden
  • 503 — server.public_base_url is not set; SAML needs it

The sign-in methods this organization accepts

The sign-in methods this organization accepts. Requires the org’s admin role.

Path parameters

NameTypeRequiredDescription
org_idstringyes

Response 200 (application/json)

{
"allowed": [
"password"
]
}
FieldTypeRequiredDescription
allowed"password" | "sso" | "social"[]yespassword, sso and/or social (Google or Microsoft). At least one.
  • 401 — Unauthorized
  • 403 — Forbidden
  • 404 — Not Found

Set the sign-in methods this organization accepts

Replaces the accepted methods: any of password, sso and social (Google or Microsoft). Requires the org’s admin role. A member’s session established by any other method gets 403 on every org-scoped endpoint until they sign in again with an accepted one. API keys are not affected.

Path parameters

NameTypeRequiredDescription
org_idstringyes

Request body (application/json)

{
"allowed": [
"password"
]
}
FieldTypeRequiredDescription
allowed"password" | "sso" | "social"[]yespassword, sso and/or social (Google or Microsoft). At least one.

Response 200 (application/json)

{
"allowed": [
"password"
]
}
FieldTypeRequiredDescription
allowed"password" | "sso" | "social"[]yespassword, sso and/or social (Google or Microsoft). At least one.
  • 401 — Unauthorized
  • 403 — Forbidden
  • 404 — Not Found

Platform-wide Google and Microsoft sign-in, configured by a superadmin under social_login_* in PATCH /admin/settings. {provider} is google or microsoft; other values return 422.

Social login callback — completes a sign-in or a link

Public. The provider redirects the browser here. It always answers with a redirect (307) into the dashboard and never with an error body:

  • /overview: signed in to an account with an organization; the session cookie is set.
  • /onboarding: signed in to an account with no organization yet, a new one included.
  • /login#mfa_token=…: the account has its own TOTP; the dashboard completes it with POST /auth/session/2fa.
  • /account?linked={provider}: a link started from /auth/me/identities/{provider}/link succeeded.
  • /login?oauth_error=<code>, or /account?oauth_error=<code> for a link attempt: the sign-in failed.

The one exception is a redirect to GET /auth/sso/{org_id}/start when an org’s SSO connection has verified the email’s domain.

Path parameters

NameTypeRequiredDescription
provider"google" | "microsoft"yes

Query parameters

NameTypeRequiredDescription
codestring | nullno
statestring | nullno
errorstring | nullno
error_descriptionstring | nullno
  • 200
  • 307 — Temporary Redirect

Which social login providers are offered — public, no auth

Public, no authentication: it carries no tenant data, only which “Continue with …” buttons the login and register pages draw. A provider is listed only when social_login_enabled, its own social_login_{provider}_enabled, and both its client ID and secret are set. {provider} across these routes is google or microsoft; other values return 422.

Response 200 (application/json)

{
"providers": [
{
"id": "string",
"label": "string"
}
],
"allow_signup": true
}
FieldTypeRequiredDescription
providersProviderInfo[]yesProviders the login page should offer. Empty when social login is off, or no provider has a complete client configured.
allow_signupbooleanyesWhether a sign-in with no matching account creates one — the register page hides its buttons when this is false.

Start a sign-in with a social login provider

Public. Redirects (307) to the provider. A short-lived oauth_state cookie holds the PKCE challenge, nonce and CSRF state for 10 minutes.

invite carries an invitation token through the round trip, so the account joins that org once signed in. terms carries the version of the operator’s terms the sign-up form accepted; when the operator requires terms, a sign-in that would create an account without the current version fails with terms_required.

Path parameters

NameTypeRequiredDescription
provider"google" | "microsoft"yes

Query parameters

NameTypeRequiredDescription
invitestring | nullno
termsstring | nullno
  • 200
  • 307 — Redirect to the provider
  • 404 — The provider is not enabled
  • 502 — The provider’s discovery document was unreachable

List the social login providers linked to the current account

The social login providers linked to the current account. Requires a session.

In the dashboard: Account, Sign-in tab, linked accounts.

Response 200 (application/json)

[
{
"provider": "string",
"email": "string",
"linked_at": "2026-01-01T00:00:00Z"
}
]
  • 400 — Bad Request
  • 401 — Unauthorized

Section titled “GET /v1/auth/me/identities/{provider}/link”

Link a social login provider to the current account

Requires a session. Redirects to the provider; the callback attaches the provider account the user picks there to this account and returns to /account?linked={provider}. Its email need not match this account’s: the user proved control of both.

Path parameters

NameTypeRequiredDescription
provider"google" | "microsoft"yes
  • 200
  • 307 — Temporary Redirect
  • 400 — Bad Request
  • 401 — Unauthorized
  • 404 — The provider is not enabled
  • 502 — Bad Gateway

Unlink a social login provider from the current account

Unlinks the provider from the current account. Requires a session.

Path parameters

NameTypeRequiredDescription
provider"google" | "microsoft"yes

Response 200 (application/json)

{
"detail": "string"
}
  • 400 — Bad Request
  • 401 — Unauthorized
  • 404 — That provider is not linked
  • 409 — It is the account’s only way to sign in: no password, no org SSO connection, no other linked provider

GET /v1/admin/social-login/{provider}/test

Section titled “GET /v1/admin/social-login/{provider}/test”

Test a sign-in provider’s saved configuration with a real round trip

Superadmin only. Tests the provider’s saved configuration with a real round trip: it redirects to the provider as a sign-in would, whether or not the provider or the master switch is on, so a configuration can be proved before anyone sees the button. The callback runs every sign-in check, then redirects to /admin/settings/sign-in?tab={provider}&test=<result> instead of signing in. No account is created or linked, and the caller’s session is untouched. Audited as social_login.test.

test= is one of:

  • ok, with email, live (1/0) and warning=sso_domain when it applies.
  • not_configured: no saved client ID and secret.
  • discovery_failed, token_exchange_failed, id_token_invalid (signature, audience or issuer; for Microsoft the tenant), provider_error: with the provider’s own error in detail.
  • email_unverified, email_missing: the refusals a sign-in would hit.
  • cancelled: the user backed out at the provider.

In the dashboard: Platform Admin → Security → Sign-in Providers.

Path parameters

NameTypeRequiredDescription
provider"google" | "microsoft"yes
  • 200
  • 307 — Temporary Redirect
  • 403 — Forbidden

SCIM 2.0 provisioning (RFC 7643/7644): an IdP such as Entra ID pushes users and groups into the org independently of login. SSO handles authentication; SCIM handles provisioning. A group is a Team.

The /orgs/{org_id}/scim routes configure SCIM and require the org’s admin role. The /scim/v2/{org_id}/* routes are the protocol surface: they accept only the org’s bearer token (Authorization: Bearer <token>), never a session or an API key, and answer 401 when the token is missing, invalid or disabled, and 403 when it belongs to another org.

default_role and every group_role_mappings[].role can never be owner, and role sync never touches a member at owner, so SCIM cannot demote or remove the org’s owner.

GET /scim/v2/{org_id}/ServiceProviderConfig

Section titled “GET /scim/v2/{org_id}/ServiceProviderConfig”

SCIM ServiceProviderConfig (discovery)

Static discovery document for the IdP’s “Test Connection” step. Authenticates with the org’s SCIM bearer token (Authorization: Bearer <token>), never a session or an API key.

Path parameters

NameTypeRequiredDescription
org_idstringyes
  • 200

SCIM ResourceTypes (discovery)

Static discovery document for the IdP’s “Test Connection” step. Authenticates with the org’s SCIM bearer token (Authorization: Bearer <token>), never a session or an API key.

Path parameters

NameTypeRequiredDescription
org_idstringyes
  • 200

SCIM Schemas (discovery)

Static discovery document for the IdP’s “Test Connection” step. Authenticates with the org’s SCIM bearer token (Authorization: Bearer <token>), never a session or an API key.

Path parameters

NameTypeRequiredDescription
org_idstringyes
  • 200

List/search Users (SCIM)

Lists and searches the org’s users. Supports filter=userName eq "..." and startIndex/count paging. Authenticates with the org’s SCIM bearer token (Authorization: Bearer <token>), never a session or an API key.

Path parameters

NameTypeRequiredDescription
org_idstringyes

Query parameters

NameTypeRequiredDescription
filterstring | nullno
startIndexintegerno
countintegerno

Response 200 (application/json)

{
"schemas": [
"string"
],
"totalResults": 0,
"itemsPerPage": 0,
"startIndex": 0,
"Resources": [
{
"schemas": [
"string"
],
"id": "string",
"userName": "string",
"name": {
"givenName": "string",
"familyName": "string"
},
"emails": [
{
"value": "string",
"primary": true
}
],
"active": true,
"meta": {
"resourceType": "User",
"location": "string"
}
}
]
}

Provision a User (SCIM)

Provisions a user: adds an existing account with that email to the org, or creates one with no password, at the config’s default_role. Never links an identity. Idempotent by email. Audited as scim.user.provisioned. Authenticates with the org’s SCIM bearer token (Authorization: Bearer <token>), never a session or an API key.

Path parameters

NameTypeRequiredDescription
org_idstringyes

Request body (application/json)

{
"userName": "string",
"name": {
"givenName": "string",
"familyName": "string"
},
"emails": [
{
"value": "string"
}
],
"active": true
}

Response 201 (application/json)

{
"schemas": [
"string"
],
"id": "string",
"userName": "string",
"name": {
"givenName": "string",
"familyName": "string"
},
"emails": [
{
"value": "string",
"primary": true
}
],
"active": true,
"meta": {
"resourceType": "User",
"location": "string"
}
}

Get one User (SCIM)

One provisioned user. Authenticates with the org’s SCIM bearer token (Authorization: Bearer <token>), never a session or an API key.

Path parameters

NameTypeRequiredDescription
org_idstringyes
user_idstringyes

Response 200 (application/json)

{
"schemas": [
"string"
],
"id": "string",
"userName": "string",
"name": {
"givenName": "string",
"familyName": "string"
},
"emails": [
{
"value": "string",
"primary": true
}
],
"active": true,
"meta": {
"resourceType": "User",
"location": "string"
}
}
  • 404 — Not Found

Replace a User (SCIM)

Replaces a user; active works as in PATCH. Authenticates with the org’s SCIM bearer token (Authorization: Bearer <token>), never a session or an API key.

Path parameters

NameTypeRequiredDescription
org_idstringyes
user_idstringyes

Request body (application/json)

{
"userName": "string",
"name": {
"givenName": "string",
"familyName": "string"
},
"emails": [
{
"value": "string"
}
],
"active": true
}

Response 200 (application/json)

{
"schemas": [
"string"
],
"id": "string",
"userName": "string",
"name": {
"givenName": "string",
"familyName": "string"
},
"emails": [
{
"value": "string",
"primary": true
}
],
"active": true,
"meta": {
"resourceType": "User",
"location": "string"
}
}
  • 404 — Not Found
  • 409 — The target is the org’s owner

Update a User, e.g. deprovision (SCIM)

Updates a user. {"active": false} deactivates the org membership (Entra ID sends this on unassignment); true reactivates it. Authenticates with the org’s SCIM bearer token (Authorization: Bearer <token>), never a session or an API key.

Path parameters

NameTypeRequiredDescription
org_idstringyes
user_idstringyes

Request body (application/json)

{
"Operations": [
{
"op": "",
"path": "string",
"value": {}
}
]
}

Response 200 (application/json)

{
"schemas": [
"string"
],
"id": "string",
"userName": "string",
"name": {
"givenName": "string",
"familyName": "string"
},
"emails": [
{
"value": "string",
"primary": true
}
],
"active": true,
"meta": {
"resourceType": "User",
"location": "string"
}
}
  • 404 — Not Found
  • 409 — The target is the org’s owner

Remove a User (SCIM)

Removes the org membership, not the account, which may belong to other orgs. Authenticates with the org’s SCIM bearer token (Authorization: Bearer <token>), never a session or an API key.

Path parameters

NameTypeRequiredDescription
org_idstringyes
user_idstringyes
  • 204
  • 404 — Not Found
  • 409 — The target is the org’s owner

List/search Groups (SCIM)

Lists and searches groups (Teams). Supports filter=displayName eq "...". Authenticates with the org’s SCIM bearer token (Authorization: Bearer <token>), never a session or an API key.

Path parameters

NameTypeRequiredDescription
org_idstringyes

Query parameters

NameTypeRequiredDescription
filterstring | nullno
startIndexintegerno
countintegerno

Response 200 (application/json)

{
"schemas": [
"string"
],
"totalResults": 0,
"itemsPerPage": 0,
"startIndex": 0,
"Resources": [
{
"schemas": [
"string"
],
"id": "string",
"userName": "string",
"name": {
"givenName": "string",
"familyName": "string"
},
"emails": [
{
"value": "string",
"primary": true
}
],
"active": true,
"meta": {
"resourceType": "User",
"location": "string"
}
}
]
}

Create a Group -> Team (SCIM)

Creates a Team named displayName. Audited as scim.group.created. Authenticates with the org’s SCIM bearer token (Authorization: Bearer <token>), never a session or an API key.

Path parameters

NameTypeRequiredDescription
org_idstringyes

Request body (application/json)

{
"displayName": "string",
"members": [
{
"value": "string"
}
]
}

Response 201 (application/json)

{
"schemas": [
"string"
],
"id": "string",
"displayName": "string",
"members": [
{
"value": "string",
"display": "string"
}
],
"meta": {
"resourceType": "User",
"location": "string"
}
}

Get one Group (SCIM)

One group (Team). Authenticates with the org’s SCIM bearer token (Authorization: Bearer <token>), never a session or an API key.

Path parameters

NameTypeRequiredDescription
org_idstringyes
team_idstringyes

Response 200 (application/json)

{
"schemas": [
"string"
],
"id": "string",
"displayName": "string",
"members": [
{
"value": "string",
"display": "string"
}
],
"meta": {
"resourceType": "User",
"location": "string"
}
}
  • 404 — Not Found

Replace a Group’s name/members (SCIM)

Replaces displayName and members, with the same role sync as PATCH. Authenticates with the org’s SCIM bearer token (Authorization: Bearer <token>), never a session or an API key.

Path parameters

NameTypeRequiredDescription
org_idstringyes
team_idstringyes

Request body (application/json)

{
"displayName": "string",
"members": [
{
"value": "string"
}
]
}

Response 200 (application/json)

{
"schemas": [
"string"
],
"id": "string",
"displayName": "string",
"members": [
{
"value": "string",
"display": "string"
}
],
"meta": {
"resourceType": "User",
"location": "string"
}
}
  • 404 — Not Found

Update a Group’s name/members (SCIM)

Updates displayName and members. Adding and removing members syncs the Team and recomputes each affected member’s role through group_role_mappings. Authenticates with the org’s SCIM bearer token (Authorization: Bearer <token>), never a session or an API key.

Path parameters

NameTypeRequiredDescription
org_idstringyes
team_idstringyes

Request body (application/json)

{
"Operations": [
{
"op": "",
"path": "string",
"value": {}
}
]
}

Response 200 (application/json)

{
"schemas": [
"string"
],
"id": "string",
"displayName": "string",
"members": [
{
"value": "string",
"display": "string"
}
],
"meta": {
"resourceType": "User",
"location": "string"
}
}
  • 404 — Not Found

Delete a Group -> Team (SCIM)

Deletes the Team, with its memberships, and recomputes every former member’s role. Authenticates with the org’s SCIM bearer token (Authorization: Bearer <token>), never a session or an API key.

Path parameters

NameTypeRequiredDescription
org_idstringyes
team_idstringyes
  • 204
  • 404 — Not Found

Get this org’s SCIM config

The org’s SCIM config. Requires the org’s admin role. token_set says whether a bearer token exists; the raw value is returned only at creation and rotation. base_url is the tenant URL to paste into the IdP.

Path parameters

NameTypeRequiredDescription
org_idstringyes

Response 200 (application/json)

{
"enabled": true,
"default_role": "owner",
"group_role_mappings": [
{
"pattern": "string",
"role": "string"
}
],
"token_set": true,
"base_url": "string",
"created_at": "2026-01-01T00:00:00Z",
"updated_at": "2026-01-01T00:00:00Z"
}
FieldTypeRequiredDescription
enabledbooleanyes
default_roleOrgRoleyes
group_role_mappingsGroupRoleMapping[]yes
token_setbooleanyes
base_urlstringyesThe tenant URL to paste into Entra ID’s SCIM provisioning setup.
created_atstring (date-time)yes
updated_atstring (date-time)yes
  • 401 — Unauthorized
  • 403 — Forbidden
  • 404 — No config

Enable SCIM provisioning for this org (e.g. Entra ID)

Turns on SCIM 2.0 provisioning for this org. Requires the org’s admin role. Returns the bearer token once: paste it into the IdP’s SCIM provisioning setup now; it cannot be read again.

group_role_mappings is an ordered list of {pattern, role} rules matched against each of the user’s current SCIM group (Team) names; the first match wins, and a user who matches none gets default_role. Neither role may be owner, and role sync never touches a member at owner, so SCIM cannot demote or remove the org’s owner.

In the dashboard: Organization → Access → SSO, SCIM provisioning tab.

Path parameters

NameTypeRequiredDescription
org_idstringyes

Request body (application/json)

{
"enabled": true,
"default_role": "owner",
"group_role_mappings": [
{
"pattern": "string",
"role": "string"
}
]
}
FieldTypeRequiredDescription
enabledbooleanno
default_roleOrgRolenoRole granted to a SCIM-provisioned user whose current groups match no group_role_mappings entry. Cannot be ‘owner’.
group_role_mappingsGroupRoleMapping[]noEvaluated in order; the first matching pattern wins.

Response 201 (application/json) — Config created; copy token now

{
"token": "string"
}
  • 401 — Unauthorized
  • 403 — Forbidden
  • 409 — A config already exists; PATCH it, or DELETE it first

Update this org’s SCIM config

All fields optional. Requires the org’s admin role. Does not touch the bearer token: rotating a live credential is always its own, separately audited call, POST /orgs/{org_id}/scim/rotate-token.

Path parameters

NameTypeRequiredDescription
org_idstringyes

Request body (application/json)

{
"enabled": true,
"default_role": "owner",
"group_role_mappings": [
{
"pattern": "string",
"role": "string"
}
]
}

Response 200 (application/json)

{
"enabled": true,
"default_role": "owner",
"group_role_mappings": [
{
"pattern": "string",
"role": "string"
}
],
"token_set": true,
"base_url": "string",
"created_at": "2026-01-01T00:00:00Z",
"updated_at": "2026-01-01T00:00:00Z"
}
FieldTypeRequiredDescription
enabledbooleanyes
default_roleOrgRoleyes
group_role_mappingsGroupRoleMapping[]yes
token_setbooleanyes
base_urlstringyesThe tenant URL to paste into Entra ID’s SCIM provisioning setup.
created_atstring (date-time)yes
updated_atstring (date-time)yes
  • 401 — Unauthorized
  • 403 — Forbidden
  • 404 — No config

Disconnect SCIM provisioning

Disconnects SCIM provisioning. Requires the org’s admin role. Removes the config and invalidates the bearer token. Teams, memberships and users SCIM created stay.

Path parameters

NameTypeRequiredDescription
org_idstringyes

Response 200 (application/json)

{
"detail": "string"
}
  • 401 — Unauthorized
  • 403 — Forbidden
  • 404 — No config

Rotate this org’s SCIM bearer token

Mints a new bearer token and invalidates the previous one at once. Requires the org’s admin role. Returns {"token": "..."} once, like creation: update the IdP’s provisioning setup right away.

Path parameters

NameTypeRequiredDescription
org_idstringyes

Response 200 (application/json)

{
"token": "string"
}
  • 401 — Unauthorized
  • 403 — Forbidden
  • 404 — No config