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

# Single Sign-On (Okta)

> Let your team sign in to Mesh API with your company's Okta, step by step.

With single sign-on (SSO), people on your company's email domain sign in to the [Dashboard](https://app.meshapi.ai) with your Okta instead of an email code. Mesh connects to Okta over OpenID Connect (OIDC).

> [!NOTE]
>
> SSO is available to **Enterprise** customers. Email [support@meshapi.ai](mailto:support@meshapi.ai) and we'll set it up for your organization. Until then, **Settings → Single sign-on** shows an upgrade notice instead of the setup form.

## Before you start

You need:

* **An owner or admin role** in the Mesh organization. Custom roles cannot change SSO.
* **Admin access to your Okta org**, to create an app and edit its policies.
* **Access to your domain's DNS**, to add one TXT record that proves you own the domain.

Setup moves between Okta and Mesh a few times, because each side needs a value the other creates. Keep both open. It takes about 15 minutes, plus however long your DNS takes to update.

## Set up SSO

**1. Create an OIDC app in Okta**

1. In the Okta Admin Console, go to **Applications → Applications → Create App Integration**.
2. Choose **OIDC - OpenID Connect**, then **Web Application**, and click **Next**.
3. Fill in the form:

   | Field | Value |
   | - | - |
   | App integration name | `Mesh` |
   | Grant type | Leave **Authorization Code** ticked |
   | Sign-in redirect URIs | `https://auth.meshapi.ai/api/auth/sso/callback/placeholder` for now. You replace it in step 4. |
   | Sign-out redirect URIs | Remove the default entry |
   | Controlled access | **Skip group assignment for now**. You assign people in step 6. |

   Okta will not save the app without a redirect URI, and Mesh only creates the real one in step 3, so a placeholder goes in first.
4. Click **Save**. On the app's **General** tab, under **Client Credentials**, copy the **Client ID** and the **Client secret**.

**2. Allow the app on Okta's authorization server**

Mesh uses Okta's **default** authorization server, whose issuer URL is `https://<your-okta-domain>/oauth2/default`. That server only issues tokens to apps one of its access policies covers. Without one, Okta signs the user in and then never sends them back to Mesh.

1. Go to **Security → API → Authorization Servers** and click **default**.
2. Open **Access Policies**. If a policy is assigned to **All clients**, skip to step 3 of this guide. Otherwise click **Add New Access Policy**:
   * **Name**: `Mesh`
   * **Assign to**: **The following clients** → select **Mesh**
   * Click **Create Policy**.
3. In that policy, click **Add Rule**:
   * **Rule name**: `Allow sign-in`
   * **Grant type**: leave **Authorization Code** ticked
   * **User is**: **Any user assigned the app**
   * **Scopes requested**: **Any scopes**
   * Click **Create Rule**.

**3. Add Okta as your identity provider in Mesh**

1. In the Dashboard, go to **Settings → Single sign-on** and click **Add identity provider**.

2. Fill in the form:

   | Field | Value |
   | - | - |
   | Issuer URL | `https://<your-okta-domain>/oauth2/default`, for example `https://acme.okta.com/oauth2/default` |
   | Client ID | From step 1 |
   | Client secret | From step 1. Mesh stores it encrypted and never shows it again. |
   | Email domain | Your company's email domain, for example `acme.com` |

3. Click **Add identity provider**. Mesh contacts the issuer URL to read Okta's configuration, so a typo in it fails here rather than at sign-in.

The provider appears as a card marked **Unverified**, showing the **Sign-in redirect URI** and a DNS record.

**4. Put the real redirect URI in Okta**

1. On the provider card in Mesh, copy the **Sign-in redirect URI**. It looks like `https://auth.meshapi.ai/api/auth/sso/callback/sso_…`.
2. In Okta, open the **Mesh** app → **General** → **Login** section → **Edit**.
3. Replace the placeholder under **Sign-in redirect URIs** with the copied URI, and click **Save**.

It must match exactly. Any difference and Okta refuses the sign-in with a `redirect_uri` error.

**5. Verify your email domain**

1. At your DNS provider, add the **TXT** record the provider card shows:
   * **Name**: `_mesh-sso.<your-domain>`, for example `_mesh-sso.acme.com`
   * **Value**: `mesh-sso-verification=sso_…`
2. Wait a few minutes for DNS to update, then click **Verify domain** on the card.

The card changes to **Verified**. Until it does, nobody can sign in with this provider.

**6. Assign people in Okta**

1. In Okta, open the **Mesh** app → **Assignments** → **Assign**, and assign the people or groups who should use Mesh.
2. Open the app's **Sign On** tab and check **User authentication**. The policy shown there decides which factors Okta asks for. If it requires two factors, everyone you assigned must have two authenticators set up in Okta, such as a password and a passkey. Okta refuses anyone who doesn't.

Everyone you assign must have an email on the domain you verified, or a subdomain of it.

**7. Test it**

1. Open a private browser window and go to [app.meshapi.ai](https://app.meshapi.ai).
2. Click **Sign in with SSO**, enter an assigned person's work email, and continue.
3. Sign in at Okta. You land back in the Mesh Dashboard.

## What happens when people sign in

* **The first SSO sign-in creates the person's Mesh account and adds them to your organization as a Member.** Change their role under **Settings → People**.
* **Okta must send an email on your verified domain.** Mesh refuses to create an account for any other address, even if Okta vouches for it.
* **Removing someone in Mesh sticks.** If you remove a member under **Settings → People**, signing in through Okta again does not re-add them. To stop them signing in at all, unassign them from the Mesh app in Okta too.
* **Unassigning someone in Okta** stops new sign-ins straight away. A session they already have lasts until it ends.

## Remove SSO

On the provider card, click the delete icon and confirm. New SSO sign-ins for that domain stop immediately, and Mesh deletes its copy of the client secret. People already signed in stay signed in until their session ends, and they can still sign in with an email code. You can then delete the **Mesh** app in Okta and the `_mesh-sso` TXT record.

## Troubleshooting

Most problems show up in Okta, not Mesh. Okta's **Reports → System Log** names the reason for each refused sign-in. Filter it by the person's email.

| What you see | Cause | Fix |
| - | - | - |
| **SSO is not set up for this email domain** | No provider in Mesh matches the email's domain | Check the **Email domain** on the provider card, and that the person used their work email |
| **SSO for this domain is not active yet** | The domain is not verified | Finish step 5 |
| Okta: **The 'redirect\_uri' parameter must be a Login redirect URI** | Okta still has the placeholder, or a different URI | Redo step 4, copying the URI from the card exactly |
| Okta: **User is not assigned to the client application** | The person is not assigned to the Mesh app | Step 6 |
| Okta: **You are not allowed to access this app** | The app's authentication policy needs factors the person has not set up. System Log shows `UNSATISFIABLE`. | Have them set up the missing authenticator in Okta, or relax the policy on the app's **Sign On** tab |
| Okta signs the person in, but they never come back to Mesh | No access policy on the default authorization server covers the app. System Log shows `app.oauth2.as.authorize` failed with `no_matching_policy`. | Step 2 |
| **We couldn't reach your identity provider** | Mesh cannot read Okta's configuration from the issuer URL | Check the issuer URL is exactly `https://<your-okta-domain>/oauth2/default`. Delete the provider and add it again with the right one. |
| **Your account's email is not on your company's SSO domain** | Okta sent an email outside the verified domain | Fix the person's primary email in Okta |
| **The sign-in link expired** | The sign-in took too long, or ran across two browsers | Start again from the sign-in page |

To change the issuer URL, client ID or client secret, delete the provider and add it again. A new provider gets a new redirect URI and DNS value, so repeat steps 4 and 5.


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