Single sign-on

The SSO surface is a thin layer over the standard auth endpoints, designed for two specific situations: a single Appmint account that spans multiple orgs, and pre-authenticated flows where the credentials arrive in the URL (typically from an IDE or external tool launching into Studio Manager).

When to use SSO routes

If your app is a single-tenant frontend with one set of users, you don't need SSO — use the standard sign-in flow. SSO matters when:

• A single user identity needs access to multiple orgs and you want one login that lists them.
• An external tool (IDE, CLI, Studio launcher) hands over a pre-issued token and wants to drop the user into the right org without prompting.
• A magic-link or OAuth callback needs a routing layer that decides which org to land in.

Routes

The SSO frontend lives at /sso/*. The two main pages:

• /sso/login — the cross-org sign-in screen. Lists organizations associated with an email, then completes auth.
• /sso/test — a developer page for verifying the wired endpoints work.

Behind these pages, the SSO route handlers wrap the standard AppEngine auth endpoints:

• POST /api/sso/login — wraps POST /profile/customer/signin (or User signin), routing to the chosen org.
• POST /api/sso/login-magic — wraps magic-link redemption.
• POST /api/sso/magic-link — wraps magic-link send.
• GET /api/sso/check-orgs/{email} — looks up which orgs the email is part of.
• GET /api/sso/oauth/{provider} — initiates an OAuth flow (GitHub, Google, Facebook).
• GET /api/sso/oauth/{provider}/callback — handles the OAuth callback and routes to the right org.

These are AppMint frontend routes (in the appmint.io Next.js app) that delegate to the AppEngine endpoints documented elsewhere in this section.

Cross-org sign-in

The flow:

1. 1

   Email lookup

   The user enters their email. The frontend calls /api/sso/check-orgs/{email}, which queries AppEngine for every Customer/User record matching that email across orgs the platform allows the lookup on.

2. 2

   Org selection

   If multiple orgs are returned, render a picker. If only one, skip ahead.

3. 3

   Credential entry

   Email + password, or magic link, or OAuth — same options as the standard sign-in. The frontend includes the chosen orgid when calling the AppEngine endpoint.

4. 4

   Session set

   On success, the SSO frontend stores cookies and redirects to the destination — typically Studio Manager or a specific tenant URL.

Pre-authenticated entry

For tools that already hold a valid AppMint token (an IDE extension, a CLI launching Studio):

/sso/login?token=...&email=...&orgId=...&devEnv=dev1

The page validates the token against AppEngine, sets cookies, and redirects without prompting. Used when the AppMint VS Code extension launches Studio for a specific dev environment, or when a CLI hands a session over to the browser.

The token is validated server-side before any cookies are set — passing an invalid token shows the regular login screen.

URL parameters

The /sso/login page accepts:

Param	Purpose
email	Pre-fill the email field
orgId	Target org (skips the org picker)
token	Pre-issued AppMint token for direct entry
devEnv	Dev environment to route into after auth

Security considerations

• All SSO cookies use httpOnly (where possible), secure in production, and sameSite: lax.
• The pre-authenticated flow only accepts tokens issued by AppEngine — no third-party JWTs.
• OAuth state is validated; CSRF protection on token-based entry is the responsibility of the issuing tool.
• Magic-link tokens have short expiry (default 15 minutes); enforced server-side regardless of which endpoint redeems them.

What it isn't

The SSO surface is not a SAML or OIDC identity provider — AppEngine doesn't currently issue SAML assertions or expose an OIDC discovery document. If you need to make AppMint an IdP for an external SaaS, that's a separate integration; talk to your account team.

For the reverse — using an external OIDC provider as the source of truth for AppMint sign-ins — Microsoft and the standard OAuth providers cover the common cases, and the magic-link flow handles email-based federation. Custom OIDC providers can be wired in by adding a new passport strategy under src/users/auth/.