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

# Set up Okta

> Create the Peeps app in Okta, verify your domain, and test single sign-on.

You need:

* An **Okta admin** who can create app integrations.
* Someone who can add a **DNS TXT record** on each of your email domains.
* One **test user** in Okta with an email on your domain.

Start by emailing [support@peepsai.com](mailto:support@peepsai.com) with your organization's name and email domains. We reply with your **Single sign-on URL** and **Audience URI**, which you need in step 1.

<Steps>
  <Step title="Create the Peeps app in Okta">
    In the Okta Admin Console, go to **Applications → Applications → Create App Integration**, choose **SAML 2.0**, and name it "Peeps". Then enter:

    | Okta setting | Value |
    | - | - |
    | Single sign-on URL | the **Single sign-on URL** we sent you |
    | Audience URI (SP Entity ID) | the **Audience URI** we sent you |
    | Name ID format | EmailAddress |
    | Application username | Email |

    Leave the signing settings at Okta's defaults.

    **Optional:** add these attribute statements so people get their real name in Peeps. Without them, a new person's name is their email address.

    | Name | Value |
    | - | - |
    | `firstName` | `user.profile.firstName` |
    | `lastName` | `user.profile.lastName` |

    Click **Finish**.
  </Step>

  <Step title="Assign people">
    On the app's **Assignments** tab, choose **Assign → Assign to People** or **Assign to Groups**. Start with your test user. Only people assigned to the app can use it.
  </Step>

  <Step title="Send us the app's metadata">
    On the app's **Sign On** tab, open the **Metadata URL**. It shows an XML document. Send us that **XML**, not the URL.

    The metadata contains Okta's sign-in address and the certificate it signs with. It's public information, not a secret.
  </Step>

  <Step title="Add the DNS record">
    We reply with a TXT record for each email domain. It proves your organization owns the domain. Add it wherever your domain's DNS is managed.

    | Field | Value |
    | - | - |
    | Type | TXT |
    | Host / Name | the host name we sent, e.g. `_better-auth-token-acme-1a2b3c4d-saml` |
    | Value | the token we sent |

    <Warning>
      **Enter only the host part.** Most DNS providers (Namecheap, GoDaddy, Cloudflare and others) add your domain to the host name for you. If you enter the full name, `_better-auth-token-…-saml.acme.com`, the record ends up at `…acme.com.acme.com` and we can't find it.
    </Warning>

    Let us know when it's added. The token is valid for 7 days; if it expires first, we send a new one.
  </Step>

  <Step title="Test it">
    Once we've verified the domain and switched SSO on, your test user goes to [app.peepsai.com/login](https://app.peepsai.com/login):

    1. Choose **Sign in with SSO**.
    2. Enter their work email and choose **Continue with SSO**.
    3. Sign in at Okta.

    They should land in your Peeps organization. Then assign everyone else in Okta.
  </Step>
</Steps>

## Tell your people

* Sign in from the Peeps login page with **Sign in with SSO**, not from the Okta dashboard tile.
* Keep using the same work email. People who already have a Peeps account keep it.

## Changing your Okta setup later

* **New Okta signing certificate:** email us before you switch over, with the app's new metadata. We set your connection up again with it, which needs the DNS record from step 4 again. SSO sign-in is unavailable until that's done, so plan the change with us. People keep their accounts, and login links and Google keep working throughout.
* **New email domain:** email us the domain. As with a certificate change, we set your connection up again, and you add DNS records for all your domains.
* **Turning SSO off:** email us. Your people can still sign in with a login link or Google.

If something doesn't work, see [Troubleshooting](/sso/troubleshooting).