Enterprise SSO

Single sign-on for your organization via SAML 2.0 or OIDC. Bring your own identity provider, Okta, Microsoft Entra ID, Google Workspace, Ping, and others, and your people reach Topolab with their corporate login instead of a magic link.

Preview, Enterprise SSO is documented here as the configuration contract and is not yet live in production. The flow below describes how the connection is set up and used; treat it as the specification rather than a feature to enable in production today.

This is an Enterprise-only capability.

How it is configured

SSO is set up by an organization admin in the portal security settings rather than assembled from raw API calls. The admin:

1. Adds the connection, chooses SAML 2.0 or OIDC and enters the identity provider's metadata (SAML metadata URL / IdP entity ID and certificate, or the OIDC issuer, client ID, and secret).
2. Adds verified domains, the email domains the organization owns (for example acme.example). Domain verification proves ownership before sign-ins from that domain are routed to your provider.
3. Optionally enforces SSO, once verified, the admin can require that all members of the organization sign in through SSO, disabling magic-link sign-in for those accounts.

How users sign in

• A user enters their work email on the sign-in screen.
• If the email's domain is a verified domain with an active SSO connection, they are routed to your identity provider, authenticate there, and land in their Topolab session, the same session a magic link would create.
• Just-in-time (JIT) provisioning: the first time someone signs in via SSO, their account is created in your organization with the right role, so there is no separate invite step.

Enforce SSO

With enforce-SSO enabled, members of the organization must authenticate through the identity provider; passwordless magic-link sign-in is turned off for them. Leave it disabled to allow both SSO and magic link during a rollout.

SAML 2.0 and OIDC

Both standards are supported, so you can connect any compliant identity provider:

• SAML 2.0, exchange SAML metadata; Topolab acts as the service provider.
• OIDC, configure the issuer, client ID, and client secret; Topolab acts as the relying party.

Endpoints

The connection is configured and used through these routes. The configuration and domain routes are portal-session calls (Authorization: Bearer <session JWT>, admin); the sign-in routes are the browser redirect flow your users hit, not calls you make yourself.

Configuration and domains (portal, admin):

Route	Purpose
GET /v1/organization/:organizationId/sso	Read the organization's SSO configuration.
PUT /v1/organization/:organizationId/sso	Create or update the organization's SSO configuration.
GET /v1/organization/:organizationId/sso/domains	List the organization's SSO email domains.
POST /v1/organization/:organizationId/sso/domains	Add an email domain to verify.
POST /v1/organization/:organizationId/sso/domains/:domainId/verify	Verify a pending domain.
DELETE /v1/organization/:organizationId/sso/domains/:domainId	Remove a domain.

Sign-in (browser redirect flow):

Route	Purpose
GET /v1/auth/sso/start	Begin sign-in by work email; the domain selects the organization's provider.
GET /v1/auth/sso/:orgId/start	Begin sign-in against a specific organization's provider.
POST /v1/auth/sso/callback	The identity provider returns here to complete authentication and establish the session.

For automated user lifecycle on top of sign-on, pair SSO with SCIM provisioning: SSO handles authentication, SCIM handles create / update / deactivate from your directory.

Next

• SCIM provisioning, directory-driven user lifecycle to pair with SSO.
• Authentication, API keys and the default passwordless sign-in.