Skip to main content
With single sign-on (SSO), people on your company’s email domain sign in to the Dashboard with your Okta instead of an email code. Mesh connects to Okta over OpenID Connect (OIDC).
SSO is available to Enterprise customers. Email 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: 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:
  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.
  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. 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.