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

> ## Agent Instructions
> Use Stable documentation by default. Honor an explicit Beta request or a URL under /docs/beta/. If the requested version conflicts with the installed CLI package or API origin, clarify the target before writing integration code.
> Pages under /docs/beta/ document Beta; other product pages document Stable. Keep the CLI package, commands, API origin, and credentials within the selected version. State the documentation version in your answer.
> For MCP search, always pass version: Stable or version: Beta. Unfiltered search mixes both versions. For filesystem reads, keep Beta queries under /beta/ and exclude /beta/ from Stable queries; discover paths before reading them.
> The public docs base is https://photon.codes/docs. Convert MCP page paths to public URLs under that base, preserving /beta/ when present. Read https://photon.codes/docs/skill.md for version selection and https://photon.codes/docs/llms.txt for the version indexes.

# Single sign-on (SSO)

> Connect your identity provider so members sign in to your organization with their company account.

> [!WARNING]
>
> **Beta is a preview.** The Beta (2.0) platform does not have all the features
> of [Stable](https://docs.photon.codes/docs/spectrum-ts/introduction.md) yet. For example, iMessage on Beta
> supports only text and images, so tapbacks, polls, message effects, and voice
> notes are [only on Stable](https://docs.photon.codes/docs/spectrum-ts/providers/imessage/messaging-features.md)
> for now. Use Stable for production agents, and confirm that Beta supports the
> features you need before you buy a plan.

Single sign-on lets members sign in to your Photon organization through your
company's identity provider (IdP), such as Okta, Microsoft Entra ID, or Google
Workspace. Photon supports SAML and OpenID Connect providers. You verify your
domain and connect your identity provider in a secure setup portal opened from
the Dashboard.

SSO costs **\$220 per organization per month** and is billed separately from
project plans. See [Billing](https://docs.photon.codes/docs/beta/billing.md#optional-resources-and-services).

## Before you start

Only an organization Owner or Admin can set up SSO. During setup, you'll add a
DNS record to verify your company's email domain and configure an application
in your identity provider. Make sure you have access to both, or have your IT
administrator available to help.

You'll be prompted to confirm and purchase the SSO subscription the first time
you open the setup portal. The charge is prorated for the remainder of your
current billing period and billed to the organization's
[payment method](https://docs.photon.codes/docs/beta/invoices-and-payments.md#payment-method).

> [!WARNING]
>
> SSO becomes required as soon as your identity provider is connected. From then
> on, every member, including you, must sign in through your identity provider.

### What happens to existing members

* Each member signs in with the company account that uses **the same email
  address** as their Photon account.
* Only members with an email address on a verified domain can sign in once SSO
  is enabled.
* Both the organization Owner and the administrator setting up SSO must use an
  email address on a verified domain. If the Owner uses a personal email, invite
  their company email address to the organization and transfer ownership to that
  account before you start.
* Anyone with an email address on your verified domains may be required to use
  SSO whenever they sign in to Photon, not only for this organization.

### Prepare your team

* Let members know when the change will happen and that they'll sign in through
  your identity provider from then on.
* Assign every member to the Photon app in your identity provider before you
  connect it.
* Choose a quiet time for the rollout, and have someone from IT available while
  members switch over.

## Set up SSO

In the Dashboard, go to **Security** > **Single sign-on**. The page guides you
through each step and saves your progress, so you can close it and return at any
time.

**1. Verify your domain**

Click **Verify domain**. The first time you open the setup portal, confirm the
SSO subscription purchase.

In the setup portal:

![Setup portal page titled Verify your organization domain, with an Enter your domain field and a Continue button.](https://mintcdn.com/photon-6d78d87b/rVkVsN7z7mproaxu/beta/images/sso/verify_domain.webp?fit=max\&auto=format\&n=rVkVsN7z7mproaxu\&q=85\&s=8094d6cf49938c184fcb924158de8348)

The setup portal asks for the domain your members' email addresses use.

1. Enter your company's email domain, such as `example.com`.
2. Copy the TXT record shown in the portal.
3. Add it to your domain's DNS settings while keeping your existing TXT
   records.

Back on the **Single sign-on** page, the domain shows **Waiting for DNS** until
the record is detected. DNS changes usually take a few minutes, but can take up
to 48 hours. Click **Check again** to refresh the status.

All verified domains for an organization must use the same identity provider.

**2. Review members**

Click **Configure SSO**. Before the setup portal opens, Photon checks your
organization's members and shows anyone who won't be able to sign in once SSO
is required:

![SSO will become required dialog, with a Who needs a company email section showing the Owner with a Company email badge, a Members without a company email section listing one member with a Remove action, and a Continue to SSO setup button.](https://mintcdn.com/photon-6d78d87b/rVkVsN7z7mproaxu/beta/images/sso/check_member.webp?fit=max\&auto=format\&n=rVkVsN7z7mproaxu\&q=85\&s=c3ca4fe16bc70cf30a07f96343be15d3)

Before the setup portal opens, Photon checks the Owner and your account, and lists members without a company email.

* **The Owner and your own account.** Both must use an email address on a
  verified domain before you can continue.
  * To change the Owner, invite the Owner's company email from **Members**,
    then transfer ownership to that account in **Settings** after the
    invitation is accepted. Only the current Owner can transfer ownership.
  * To continue with a different account, sign in with a company account
    that has the Owner or Admin role, or ask another administrator to finish
    setup.
* **Members without a company email.** Members whose email address isn't on
  a verified domain won't be able to sign in once SSO is required. You can
  remove them now or leave them in the organization until they switch to a
  company account.

Click **Continue to SSO setup** when you're ready.

**3. Connect your identity provider**

Follow the instructions in the setup portal to connect your identity
provider, then test the connection in the portal.

For provider-specific setup instructions, see:

* [Okta SAML](https://workos.com/docs/integrations/okta-saml)
* [Entra ID SAML (formerly Azure AD)](https://workos.com/docs/integrations/entra-id-saml)
* [Google SAML](https://workos.com/docs/integrations/google-saml)
* [OneLogin SAML](https://workos.com/docs/integrations/onelogin-saml)
* [JumpCloud SAML](https://workos.com/docs/integrations/jumpcloud-saml)
* [Duo SAML](https://workos.com/docs/integrations/duo-saml)
* [Cloudflare Access SAML](https://workos.com/docs/integrations/cloudflare-saml)

As soon as the connection becomes active, SSO is required for the
organization.

**4. Verify sign-in**

Back on the **Single sign-on** page, click **Sign in with SSO** and sign in
with your company account to confirm the connection works end to end. Once
verified, the connection status shows **Active**.

## After setup

### Share the company sign-in link

Copy the **Company sign-in link** from the **Single sign-on** page and share it
with your team. It sends members directly to your identity provider to sign in.

### Let new people join automatically

Under **Joining**, click **Let new users join as Viewer** to turn on **Automatic
joining**. Anyone who signs in through your identity provider can then join the
organization automatically as a **Viewer**, and you can update their role
afterward.

Invited users still join with the role assigned in their invitation. Members who
were previously removed from the organization cannot rejoin automatically and
always require a new invitation.

### Remove someone's access

Deactivating a user in your identity provider prevents them from signing in
again, but any connected apps, MCP clients, or personal keys they already set up
will keep working. To revoke their access immediately, remove them from
**Members** as well.

## Manage the connection

Click **Manage SSO** to open the setup portal when you need to update your
configuration—for example, to rotate a SAML certificate or an OpenID Connect
client secret, or to adjust attribute mapping. After making changes, click
**Test sign-in** to verify the connection. Modifying the connection signs
existing members out of the organization until they sign in again.

Click **Manage domains** to add or verify additional domains.

> [!WARNING]
>
> To stop using SSO, [turn it off](#turn-off-sso) in the Dashboard. Don't delete
> the connection in the setup portal—doing so locks everyone out of the
> organization, including you.

> [!TIP]
>
> Rotate your SAML certificate or OpenID Connect client secret before it
> expires to avoid sign-in disruptions.

## Turn off SSO

In **Danger zone**, click **Turn off**. Choose your domain and subscription
options, type `turn off sso` to confirm, and submit:

* The connection to your identity provider is deleted, and members sign in
  without SSO.
* Automatic joining stops, so new members need an invitation to join.
* Verified domains are unbound by default unless you uncheck them. Unbound
  domains must be verified again before you can use them with SSO in the future.
* You choose what happens to the SSO subscription:
  * **End the SSO subscription.** The subscription ends immediately, and any
    unused days are credited back to the organization.
  * **Keep the subscription.** The subscription continues to renew so you can
    set up SSO again without repurchasing it. You can also end it later under
    **Subscription** on the **Single sign-on** page.

If a step fails while turning off SSO, click **Try again** to resume from where
it left off.

## Troubleshooting

> [accordion] The domain stays on Waiting for DNS
>
> * Add the TXT record to the exact domain you entered, not to a subdomain
>   such as `www`. Use a DNS lookup tool to confirm the record is published.
> * Copy the record value exactly as shown in the setup portal.
> * Allow up to 48 hours for DNS changes to propagate, then click **Check
>   again**.

> [accordion] Your company sign-in worked, but this organization hasn't given you access
>
> Ask an Owner or Admin to send you an invitation or turn on automatic
> joining.

> [accordion] You're signed in to Photon as someone else
>
> Sign out of the Dashboard, then open the company sign-in link again.

> [accordion] Nobody can sign in to this organization
>
> Contact [support@photon.codes](mailto:support@photon.codes) from the Owner's
> email address. We'll verify ownership and help you restore access.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.