SSO and domains

Before you start

• You need the organization's SSO permission (owners and admins). Other members see "Only organization admins and owners can view SSO configuration."
• Your plan must include Enterprise SSO (Business or Enterprise; the pricing page lists it).
• You will claim an email domain you control. Public mail domains such as gmail.com cannot be claimed.
• From your IdP you need either an OIDC issuer, client ID and client secret, or a SAML entity ID, SSO URL and signing certificate.

Connect an identity provider

1. Step 101

   Choose the protocol

   Open Settings → SSO (?settings=sso) and pick OpenID Connect — recommended or SAML 2.0.
2. Step 202

   Choose the provider

   Okta, Microsoft Entra, Google Workspace or Custom. A preset only prefills the issuer, for example https://login.microsoftonline.com/{tenant-id}/v2.0.
3. Step 303

   Configure

   OIDC: Issuer URL, Client ID, Client secret. Akili fetches <issuer>/.well-known/openid-configuration itself. SAML: Issuer (IdP entity ID), Entry point (SSO URL), X.509 certificate. Both: the Domain claim, the email domain whose users are directed to this provider.
4. Step 404

   Register the callback at your IdP

   Akili generates a provider ID. OIDC redirects and the SAML assertion consumer URL are built from it under your auth service base, for example {auth base}/api/auth/sso/saml2/callback/{providerId}.
5. Step 505

   Verify the domain claim

   Press Request verification token, add the TXT record shown, then Verify domain. Until the status reads Domain verified, sign-in does not route the domain to this provider.

You can register more than one provider, each with its own domain claim.

Verify a domain

There are two DNS checks, each with its own TXT record, and they do different jobs.

The SSO provider check

Part of the SSO wizard. It proves the domain claim on one provider and is what turns on SSO routing for that domain.

_better-auth-token-<providerId>.<your-domain>   TXT   <token from "Request verification token">

The Domains tab

Settings → Domains (?settings=domains) claims the domain for the organization as a whole. Add the domain, create the record, then verify; the status moves from Pending to Verified, or Not verified when DNS has not propagated yet (retry later).

_akili-challenge.<your-domain>   TXT   akili-domain-verification=<token>

A verified domain does two things today:

• Sign-in with an email at that domain (subdomains included) is routed to your SSO provider when one is verified for it.
• Magic-link sign-in with an email at a claimed domain is refused unless the person is already a member or has a pending invitation; they see "Ask your domain administrator for access to Akili." and can press Request access to notify your admins.

Require SSO and auto-join

While Require SSO is on, a non-SSO session gets AUTH_SSO_REQUIRED and the sign-in page shows “Your organization requires SSO sign-in.” New sign-ups are never blocked, and the policies endpoint stays reachable so an SSO-signed-in owner can change the setting.

Provisioning (SCIM and just-in-time)

• Just-in-time accounts. The first SSO sign-in creates the Akili account. Membership follows only with an invitation or the auto-join policy.
• SCIM provisioning. Akili exposes /scim/v2/Users (SCIM 2.0 core: create, list with filter=userName eq "…", get, replace, patch, delete) plus the discovery endpoints /scim/v2/ServiceProviderConfig, /ResourceTypes and /Schemas, authenticated with a bearer token issued at /scim/tokens by a member with the SCIM permission. Creating a user adds the person to the organization as a member: an existing Akili account is linked by email; otherwise a passwordless account is created that signs in with SSO or a magic link. Setting active to false (or deleting) removes the member and its org roles, and refuses to remove the last owner. Names and externalId update in place; an email change needs the current address to be on a domain you have verified. /scim/v2/Groups is read-only (the organization as one group; group push answers 501). There is no SCIM screen in Settings yet; use the API.
• Linking to an existing account. An SSO identity attaches to an existing Akili account with the same email only when that email is verified; otherwise sign-in ends with “account not linked” and a verification email is sent.

Enterprise sign-in client for connectors

In Settings → Connectors, the Enterprise sign-in client form registers an OAuth client at your IdP so Akili can exchange a member’s sign-in for tokens that MCP connectors accept (identity-assertion token exchange). You can reuse your SSO app’s client or register a dedicated one, and authenticate it with a secret in the body, a secret in the header, or a private-key JWT.

What members see at sign-in

1. Step 101

   Email first

   The sign-in page asks for the email address and Continue. Akili checks the domain.
2. Step 202

   Single sign-on detected

   If the domain has a verified provider the page shows Single sign-on detected, the note that signing in confirms identity but does not grant workspace access, and Sign in with {provider}. Use a different account goes back.
3. Step 303

   Your IdP, then back to Akili

   The browser goes to the IdP and returns to the callback. A domain without SSO falls through to the normal method step (password, magic link, email code, social or passkey).

Troubleshooting

Good to know

• Reading versus changing. Viewing SSO needs the SSO read permission; registering, updating or deleting a provider needs SSO write, and the server enforces both.
• Two-factor with SSO. Security settings show “Managed by your identity provider” for two-factor and recovery codes on SSO accounts; enforce MFA at the IdP.
• Provider ID is random. It is generated in the browser when you create the provider; copy it from the saved provider when building callback URLs.
• Members and seats. Auto-join adds members without a seat check. See Organization.