> ## Documentation Index
> Fetch the complete documentation index at: https://docs.semicola.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Single sign-on

> Let your organization's members sign in with your corporate identity provider (Okta, Azure AD, Google Workspace and others).

Single sign-on (SSO) lets your members sign in with your corporate identity provider instead of a
separate login. SSO is set up once for the organization, through the identity provider's hosted setup
portal.

<Info>An admin sets up SSO. If you aren't an admin, ask one to follow this guide.</Info>

## Before you start

* You're an admin of the account.
* Someone with access to your identity provider's admin console is available; setup needs its SAML
  metadata or equivalent.
* Your account's company domain is registered and **verified**. SSO stays locked until it is.

## Set it up

1. Open **Settings** in the app and go to **Single sign-on (SSO)**. (An organization's own settings
   don't show it; open it from one of its accounts.)
2. If the section says **Verify your brand domain first**, register your domain (see
   [Registered domain](/guides/accounts#registered-domain)). A domain matching your verified email is
   verified at once; any other waits for Semicola staff approval.
3. Choose **Open setup portal**. The portal opens in a new tab.
4. In the portal:
   * Select your identity provider (for example Okta, Azure AD or Google Workspace).
   * Follow its configuration steps: metadata, attribute mapping and any provider-specific settings.
   * Complete the connection and verify it works.
5. When the test passes, your members can sign in with their corporate credentials.

SSO applies to the organization, so every account under it shares one connection. To change or
replace the identity provider later, choose **Open setup portal** again (**Update identity provider
settings**).

## Over the API

| Endpoint                       | What it does                                                               |
| ------------------------------ | -------------------------------------------------------------------------- |
| `GET /api/v2/sso/organization` | The organization's current SSO connection, or `null`.                      |
| `POST /api/v2/sso/setup`       | A one-time `link` to the setup portal. `409` until the domain is verified. |

Both need an admin.

## Troubleshooting

* **"Verify your brand domain first"**: the account's domain isn't verified yet.
* **The portal link stopped working**: generate a new one with **Open setup portal**.
* **"Single sign-on setup is not available in this environment yet."**: the identity provider isn't
  configured for this deployment.
* **A sign-in times out**: retry once in a fresh browser session. If it fails again, file a support
  ask with the time (and time zone), your domain, identity provider, browser, and the stage that
  failed. Never send cookies, tokens, passwords or SAML assertions.