> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended** (the `-y` flags skip prompts, so the command runs without an interactive terminal):
> ```bash
> npx -y @scalekit-inc/cli setup -y
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup -y
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents in `~/.agents/skills`.
> Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# How Modular SSO works

The parts of a Modular SSO login: environments, organizations, connections, domains, redirect URLs, and the profile and tokens your callback receives.
This page explains the parts of a Modular SSO login and how they fit together. Read it after the [quickstart](/authenticate/sso/add-modular-sso/), or before it if you want the whole picture first.

## Environment

An environment holds everything for one stage of your app, such as development or production: its own API credentials, environment URL, organizations and connections. Its credentials are under **Developers** > **Settings** > **API Credentials** in the dashboard.

To use Modular SSO, set the environment's authentication mode to **Modular Auth** in **Settings** > **Authentication Mode**. In this mode your app keeps its users and sessions, and Scalekit returns the verified user to your app.

A development environment comes with a test organization and an SSO simulator, so you can test before you have a customer. See [Test SSO](/sso/guides/test-sso/).

## Organization

An organization is one of your customers, usually a company, such as Megacorp. Create one for each customer that wants SSO, in the dashboard or with the API. Its ID starts with `org_`.

Store the organization ID with the customer's record in your app. You use it to start their users' logins, and the ID token at the end of each login tells you which organization the user belongs to.

## Connection

A connection links an organization to its identity provider (IdP), such as Okta or Microsoft Entra ID, over SAML or OIDC. Its ID starts with `conn_`.

Usually your customer's IT admin sets up the connection in the [admin portal](/authenticate/sso/admin-portal/): they enter the IdP's details and test the login. You can also set it up for them from the organization's page in the dashboard. Each IdP's setup steps are in the [IdP guides](/guides/integrations/sso-integrations/).

## Domain

An organization's domains are the email domains its users sign in with, such as `megacorp.com`. With a domain on the organization, your app can send a user to the right IdP from their email address alone, without asking which company they're from. See [Route users to SSO by email domain](/guides/user-auth/check-sso-domain/).

## Redirect URLs

Scalekit only sends users to URLs you've registered under **Authentication** > **Redirect URLs**:

- **Allowed callback URL**: where Scalekit sends the user at the end of a login, with a one-time code. Your app exchanges the code for the user's profile.
- **Initiate login URL**: where Scalekit sends a user who started from their IdP's dashboard, so your app can start the login itself.

See [Register redirect URLs](/authenticate/sso/redirect-urls/).

## Start a login: the authorization URL

Your app starts a login by redirecting the user to an authorization URL that the SDK builds. The URL names your callback URL and the customer, by one of:

- the connection ID
- the organization ID
- a domain hint, such as `megacorp.com`
- a login hint, the user's email address, whose domain picks the organization

If you pass more than one, Scalekit uses them in a fixed order. See [Authorization URL parameters](/sso/guides/authorization-url/#parameter-precedence).

Pass a `state` value too. Scalekit returns it unchanged to your callback, so your app can check that the response belongs to a login it started.

## IdP-initiated login

Some users start from their IdP's dashboard, such as an app tile in Okta. Scalekit sends them to your initiate login URL with an `idp_initiated_login` token. Your endpoint reads the organization and connection from the token and starts a normal login with an authorization URL. See [IdP-initiated SSO](/sso/guides/idp-init-sso/).

## What your callback receives

At the end of a login, Scalekit redirects the user to your callback URL with a `code` and the `state` you sent, or with `error` and `error_description` if the login failed. Your app exchanges the code with the SDK and gets:

- **The user's profile**: email, name and the other fields of the [normalized user profile](/sso/guides/user-profile-details/), in the same format for every IdP.
- **An ID token**: a signed JWT with the same profile. Its `sub` claim is the connection ID and the user's ID at the IdP, joined by `;`. Its `oid` claim is the organization ID.
- **An access token**.

There's no refresh token: after the login, your app runs the session. To find or create the user in your database, see [Handle the callback and find the user](/authenticate/sso/handle-callback/).

## Admin portal

The admin portal is a page Scalekit hosts where your customer's IT admin sets up and tests their SSO connection. Share a link to it, or embed it in your app's settings page. See [Admin portal](/authenticate/sso/admin-portal/).

## Events

Scalekit sends webhook events when a customer's SSO connection is created, enabled, disabled or deleted, so your app can turn SSO on for the customer at the right time. See [SSO events](/sso/reference/sso-events/).

## Next

  - [Choose how to integrate](/authenticate/sso/choose-integration/): Your own code, or an auth system such as Auth0, Cognito, Firebase or Supabase.
  - [Handle the callback and find the user](/authenticate/sso/handle-callback/): Check the response, find or create the user and start your session.


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |