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.
GET /auth/sso/callback
Section titled “GET /auth/sso/callback”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:
- An account already linked to this identity signs in.
- 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 throughGET /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. - 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
| Name | Type | Required | Description |
|---|---|---|---|
code | string | yes | |
state | string | yes |
200307— Signed in, or sent to the login page to link or to enter a TOTP code400— Missing, expired or tampered state, or the code exchange or ID-token check failed403— The email’s domain is not inallowed_domains, or the account is deactivated409— A link attempt with an IdP account already linked to another account502— The identity provider was unreachable
GET /auth/sso/saml/{org_id}/metadata
Section titled “GET /auth/sso/saml/{org_id}/metadata”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
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
200503—server.public_base_urlis not set; SAML needs it
POST /auth/sso/saml/{org_id}/acs
Section titled “POST /auth/sso/saml/{org_id}/acs”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
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
303— Verified; continue at/auth/sso/saml/complete400— No enabled SAML connection, or the response failed a check; the detail says which503—server.public_base_urlis not set; SAML needs it
GET /auth/sso/saml/complete
Section titled “GET /auth/sso/saml/complete”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
| Name | Type | Required | Description |
|---|---|---|---|
ticket | string | yes |
200307— Signed in, or sent to the login page to link or to enter a TOTP code400— Ticket expired or used, missing or expiredsso_state, or a response that answers another browser’s request403— The email’s domain is not inallowed_domains, or the account is deactivated409— A link attempt with an IdP account already linked to another account
POST /v1/auth/sso/discover
Section titled “POST /v1/auth/sso/discover”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
GET /v1/auth/sso/{org_id}/start
Section titled “GET /v1/auth/sso/{org_id}/start”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
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
invite | string | null | no |
200307— Redirect to the IdP404— No enabled connection for this org502— The identity provider was unreachable503—server.public_base_urlis not set; SAML needs it
GET /v1/auth/sso/{org_id}/link
Section titled “GET /v1/auth/sso/{org_id}/link”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
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
200307— Redirect to the IdP, or to the login page when the account is not a member400— Called with an API key instead of a session401— Not signed in403— Started from another site404— No enabled connection for this org502— The identity provider was unreachable
GET /v1/orgs/{org_id}/sso
Section titled “GET /v1/orgs/{org_id}/sso”Get this org’s SSO connection
The org’s SSO connection. Requires the org’s admin role.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
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"}| Field | Type | Required | Description |
|---|---|---|---|
protocol | "oidc" | "saml" | yes | |
display_name | string | yes | |
issuer | string | null | no | OIDC only |
client_id | string | null | no | OIDC only |
client_secret_set | boolean | no | OIDC only |
idp_entity_id | string | null | no | SAML only |
idp_sso_url | string | null | no | SAML only |
idp_certificates | SAMLCertificateInfo[] | no | SAML only |
email_attribute | string | null | no | SAML only |
service_provider | SAMLServiceProviderInfo | null | no | SAML only |
default_role | OrgRole | yes | |
allowed_domains | string[] | null | no | |
verified_domains | string[] | no | The allowed domains whose DNS proves this org controls them. Only these route sign-ins to this connection. |
domain_verification_record | string | yes | The TXT value to publish at _opentremor-challenge. |
enabled | boolean | yes | |
created_at | string (date-time) | yes | |
updated_at | string (date-time) | yes |
401— Unauthorized403— Forbidden404— No connection configured
POST /v1/orgs/{org_id}/sso
Section titled “POST /v1/orgs/{org_id}/sso”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
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
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}| Field | Type | Required | Description |
|---|---|---|---|
protocol | "oidc" | "saml" | no | Cannot change later: delete the connection and create a new one. |
display_name | string | yes | Shown on the login page’s SSO button, e.g. ‘Acme Corp’ |
issuer | string | null | no | OIDC: issuer URL, e.g. https://login.microsoftonline.com/{tenant}/v2.0 |
client_id | string | null | no | OIDC: the client id the IdP issued |
client_secret | string | null | no | OIDC: encrypted at rest and never returned. |
idp_entity_id | string | null | no | SAML: the IdP’s entity id (the assertions’ Issuer) |
idp_sso_url | string | null | no | SAML: the IdP’s sign-in URL for the HTTP-Redirect binding |
idp_certificates | string[] | null | no | SAML: the IdP’s signing certificates, PEM or bare base64. List two to overlap a rotation. |
idp_metadata_xml | string | null | no | SAML 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_attribute | string | null | no | SAML: the attribute that carries the email. Unset: NameID when its format is an email address, else the usual email attributes. |
default_role | OrgRole | no | Role granted to a user auto-provisioned on their first SSO login. Cannot be ‘owner’. |
allowed_domains | string[] | null | no | Optional 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). |
enabled | boolean | no |
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"}| Field | Type | Required | Description |
|---|---|---|---|
protocol | "oidc" | "saml" | yes | |
display_name | string | yes | |
issuer | string | null | no | OIDC only |
client_id | string | null | no | OIDC only |
client_secret_set | boolean | no | OIDC only |
idp_entity_id | string | null | no | SAML only |
idp_sso_url | string | null | no | SAML only |
idp_certificates | SAMLCertificateInfo[] | no | SAML only |
email_attribute | string | null | no | SAML only |
service_provider | SAMLServiceProviderInfo | null | no | SAML only |
default_role | OrgRole | yes | |
allowed_domains | string[] | null | no | |
verified_domains | string[] | no | The allowed domains whose DNS proves this org controls them. Only these route sign-ins to this connection. |
domain_verification_record | string | yes | The TXT value to publish at _opentremor-challenge. |
enabled | boolean | yes | |
created_at | string (date-time) | yes | |
updated_at | string (date-time) | yes |
401— Unauthorized403— Forbidden409— A connection already exists;PATCHit, orDELETEit before creating a new one503—server.public_base_urlis not set; SAML needs it
PATCH /v1/orgs/{org_id}/sso
Section titled “PATCH /v1/orgs/{org_id}/sso”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
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
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}| Field | Type | Required | Description |
|---|---|---|---|
display_name | string | null | no | |
issuer | string | null | no | |
client_id | string | null | no | |
client_secret | string | null | no | |
idp_entity_id | string | null | no | |
idp_sso_url | string | null | no | |
idp_certificates | string[] | null | no | |
idp_metadata_xml | string | null | no | SAML 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_attribute | string | null | no | |
default_role | OrgRole | null | no | |
allowed_domains | string[] | null | no | Optional 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). |
enabled | boolean | null | no |
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"}| Field | Type | Required | Description |
|---|---|---|---|
protocol | "oidc" | "saml" | yes | |
display_name | string | yes | |
issuer | string | null | no | OIDC only |
client_id | string | null | no | OIDC only |
client_secret_set | boolean | no | OIDC only |
idp_entity_id | string | null | no | SAML only |
idp_sso_url | string | null | no | SAML only |
idp_certificates | SAMLCertificateInfo[] | no | SAML only |
email_attribute | string | null | no | SAML only |
service_provider | SAMLServiceProviderInfo | null | no | SAML only |
default_role | OrgRole | yes | |
allowed_domains | string[] | null | no | |
verified_domains | string[] | no | The allowed domains whose DNS proves this org controls them. Only these route sign-ins to this connection. |
domain_verification_record | string | yes | The TXT value to publish at _opentremor-challenge. |
enabled | boolean | yes | |
created_at | string (date-time) | yes | |
updated_at | string (date-time) | yes |
401— Unauthorized403— Forbidden404— No connection configured409— Conflict
DELETE /v1/orgs/{org_id}/sso
Section titled “DELETE /v1/orgs/{org_id}/sso”Disconnect this org’s SSO connection
Disconnects the org’s SSO connection. Users and memberships stay. Requires the org’s admin role.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Response 200 (application/json)
{ "detail": "string"}401— Unauthorized403— Forbidden404— 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
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes | |
domain | string | yes |
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"}| Field | Type | Required | Description |
|---|---|---|---|
protocol | "oidc" | "saml" | yes | |
display_name | string | yes | |
issuer | string | null | no | OIDC only |
client_id | string | null | no | OIDC only |
client_secret_set | boolean | no | OIDC only |
idp_entity_id | string | null | no | SAML only |
idp_sso_url | string | null | no | SAML only |
idp_certificates | SAMLCertificateInfo[] | no | SAML only |
email_attribute | string | null | no | SAML only |
service_provider | SAMLServiceProviderInfo | null | no | SAML only |
default_role | OrgRole | yes | |
allowed_domains | string[] | null | no | |
verified_domains | string[] | no | The allowed domains whose DNS proves this org controls them. Only these route sign-ins to this connection. |
domain_verification_record | string | yes | The TXT value to publish at _opentremor-challenge. |
enabled | boolean | yes | |
created_at | string (date-time) | yes | |
updated_at | string (date-time) | yes |
401— Unauthorized403— Forbidden404— No connection configured, or the domain is not inallowed_domains409— 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
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Response 200 (application/json)
{ "entity_id": "string", "acs_url": "string", "metadata_url": "string"}| Field | Type | Required | Description |
|---|---|---|---|
entity_id | string | yes | The SP entity id, also the URL of its metadata |
acs_url | string | yes | Assertion Consumer Service URL, HTTP-POST binding |
metadata_url | string | yes |
401— Unauthorized403— Forbidden503—server.public_base_urlis not set; SAML needs it
GET /v1/orgs/{org_id}/sign-in-methods
Section titled “GET /v1/orgs/{org_id}/sign-in-methods”The sign-in methods this organization accepts
The sign-in methods this organization accepts. Requires the org’s admin role.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Response 200 (application/json)
{ "allowed": [ "password" ]}| Field | Type | Required | Description |
|---|---|---|---|
allowed | "password" | "sso" | "social"[] | yes | password, sso and/or social (Google or Microsoft). At least one. |
401— Unauthorized403— Forbidden404— Not Found
PUT /v1/orgs/{org_id}/sign-in-methods
Section titled “PUT /v1/orgs/{org_id}/sign-in-methods”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
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Request body (application/json)
{ "allowed": [ "password" ]}| Field | Type | Required | Description |
|---|---|---|---|
allowed | "password" | "sso" | "social"[] | yes | password, sso and/or social (Google or Microsoft). At least one. |
Response 200 (application/json)
{ "allowed": [ "password" ]}| Field | Type | Required | Description |
|---|---|---|---|
allowed | "password" | "sso" | "social"[] | yes | password, sso and/or social (Google or Microsoft). At least one. |
401— Unauthorized403— Forbidden404— Not Found
Social login
Section titled “Social login”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.
GET /auth/oauth/{provider}/callback
Section titled “GET /auth/oauth/{provider}/callback”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 withPOST /auth/session/2fa./account?linked={provider}: a link started from/auth/me/identities/{provider}/linksucceeded./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
| Name | Type | Required | Description |
|---|---|---|---|
provider | "google" | "microsoft" | yes |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
code | string | null | no | |
state | string | null | no | |
error | string | null | no | |
error_description | string | null | no |
200307— Temporary Redirect
GET /v1/auth/providers
Section titled “GET /v1/auth/providers”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}| Field | Type | Required | Description |
|---|---|---|---|
providers | ProviderInfo[] | yes | Providers the login page should offer. Empty when social login is off, or no provider has a complete client configured. |
allow_signup | boolean | yes | Whether a sign-in with no matching account creates one — the register page hides its buttons when this is false. |
GET /v1/auth/oauth/{provider}/start
Section titled “GET /v1/auth/oauth/{provider}/start”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
| Name | Type | Required | Description |
|---|---|---|---|
provider | "google" | "microsoft" | yes |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
invite | string | null | no | |
terms | string | null | no |
200307— Redirect to the provider404— The provider is not enabled502— The provider’s discovery document was unreachable
GET /v1/auth/me/identities
Section titled “GET /v1/auth/me/identities”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 Request401— Unauthorized
GET /v1/auth/me/identities/{provider}/link
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
| Name | Type | Required | Description |
|---|---|---|---|
provider | "google" | "microsoft" | yes |
200307— Temporary Redirect400— Bad Request401— Unauthorized404— The provider is not enabled502— Bad Gateway
DELETE /v1/auth/me/identities/{provider}
Section titled “DELETE /v1/auth/me/identities/{provider}”Unlink a social login provider from the current account
Unlinks the provider from the current account. Requires a session.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
provider | "google" | "microsoft" | yes |
Response 200 (application/json)
{ "detail": "string"}400— Bad Request401— Unauthorized404— That provider is not linked409— 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, withemail,live(1/0) andwarning=sso_domainwhen 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 indetail.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
| Name | Type | Required | Description |
|---|---|---|---|
provider | "google" | "microsoft" | yes |
200307— Temporary Redirect403— Forbidden
SCIM provisioning
Section titled “SCIM provisioning”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
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
200
GET /scim/v2/{org_id}/ResourceTypes
Section titled “GET /scim/v2/{org_id}/ResourceTypes”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
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
200
GET /scim/v2/{org_id}/Schemas
Section titled “GET /scim/v2/{org_id}/Schemas”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
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
200
GET /scim/v2/{org_id}/Users
Section titled “GET /scim/v2/{org_id}/Users”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
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
filter | string | null | no | |
startIndex | integer | no | |
count | integer | no |
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" } } ]}POST /scim/v2/{org_id}/Users
Section titled “POST /scim/v2/{org_id}/Users”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
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
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 /scim/v2/{org_id}/Users/{user_id}
Section titled “GET /scim/v2/{org_id}/Users/{user_id}”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
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes | |
user_id | string | yes |
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
PUT /scim/v2/{org_id}/Users/{user_id}
Section titled “PUT /scim/v2/{org_id}/Users/{user_id}”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
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes | |
user_id | string | yes |
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 Found409— The target is the org’s owner
PATCH /scim/v2/{org_id}/Users/{user_id}
Section titled “PATCH /scim/v2/{org_id}/Users/{user_id}”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
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes | |
user_id | string | yes |
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 Found409— The target is the org’s owner
DELETE /scim/v2/{org_id}/Users/{user_id}
Section titled “DELETE /scim/v2/{org_id}/Users/{user_id}”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
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes | |
user_id | string | yes |
204404— Not Found409— The target is the org’s owner
GET /scim/v2/{org_id}/Groups
Section titled “GET /scim/v2/{org_id}/Groups”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
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
filter | string | null | no | |
startIndex | integer | no | |
count | integer | no |
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" } } ]}POST /scim/v2/{org_id}/Groups
Section titled “POST /scim/v2/{org_id}/Groups”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
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
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 /scim/v2/{org_id}/Groups/{team_id}
Section titled “GET /scim/v2/{org_id}/Groups/{team_id}”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
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes | |
team_id | string | yes |
Response 200 (application/json)
{ "schemas": [ "string" ], "id": "string", "displayName": "string", "members": [ { "value": "string", "display": "string" } ], "meta": { "resourceType": "User", "location": "string" }}404— Not Found
PUT /scim/v2/{org_id}/Groups/{team_id}
Section titled “PUT /scim/v2/{org_id}/Groups/{team_id}”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
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes | |
team_id | string | yes |
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
PATCH /scim/v2/{org_id}/Groups/{team_id}
Section titled “PATCH /scim/v2/{org_id}/Groups/{team_id}”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
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes | |
team_id | string | yes |
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 /scim/v2/{org_id}/Groups/{team_id}
Section titled “DELETE /scim/v2/{org_id}/Groups/{team_id}”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
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes | |
team_id | string | yes |
204404— Not Found
GET /v1/orgs/{org_id}/scim
Section titled “GET /v1/orgs/{org_id}/scim”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
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
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"}| Field | Type | Required | Description |
|---|---|---|---|
enabled | boolean | yes | |
default_role | OrgRole | yes | |
group_role_mappings | GroupRoleMapping[] | yes | |
token_set | boolean | yes | |
base_url | string | yes | The tenant URL to paste into Entra ID’s SCIM provisioning setup. |
created_at | string (date-time) | yes | |
updated_at | string (date-time) | yes |
401— Unauthorized403— Forbidden404— No config
POST /v1/orgs/{org_id}/scim
Section titled “POST /v1/orgs/{org_id}/scim”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
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Request body (application/json)
{ "enabled": true, "default_role": "owner", "group_role_mappings": [ { "pattern": "string", "role": "string" } ]}| Field | Type | Required | Description |
|---|---|---|---|
enabled | boolean | no | |
default_role | OrgRole | no | Role granted to a SCIM-provisioned user whose current groups match no group_role_mappings entry. Cannot be ‘owner’. |
group_role_mappings | GroupRoleMapping[] | no | Evaluated in order; the first matching pattern wins. |
Response 201 (application/json) — Config created; copy token now
{ "token": "string"}401— Unauthorized403— Forbidden409— A config already exists;PATCHit, orDELETEit first
PATCH /v1/orgs/{org_id}/scim
Section titled “PATCH /v1/orgs/{org_id}/scim”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
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
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"}| Field | Type | Required | Description |
|---|---|---|---|
enabled | boolean | yes | |
default_role | OrgRole | yes | |
group_role_mappings | GroupRoleMapping[] | yes | |
token_set | boolean | yes | |
base_url | string | yes | The tenant URL to paste into Entra ID’s SCIM provisioning setup. |
created_at | string (date-time) | yes | |
updated_at | string (date-time) | yes |
401— Unauthorized403— Forbidden404— No config
DELETE /v1/orgs/{org_id}/scim
Section titled “DELETE /v1/orgs/{org_id}/scim”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
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Response 200 (application/json)
{ "detail": "string"}401— Unauthorized403— Forbidden404— No config
POST /v1/orgs/{org_id}/scim/rotate-token
Section titled “POST /v1/orgs/{org_id}/scim/rotate-token”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
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Response 200 (application/json)
{ "token": "string"}401— Unauthorized403— Forbidden404— No config