Single sign-on

Let members sign in through your company's identity provider over SAML, and require it for your organization.

Single sign-on (SSO) lets people at your company sign in to Lingo.dev through your identity provider, such as Okta or Microsoft Entra ID. You connect the provider once over SAML 2.0. After that, anyone your provider lets in with an email at one of your connected domains joins your organization on their first sign-in, with no invitation.

You can also require SSO. Then the organization opens only for people who signed in through your identity provider.

Before you start #

  • SSO is part of the Enterprise plan. See Billing and Feature access.
  • The settings live in Settings → SSO.
  • Only an Owner can connect, change, require or disconnect SSO. Members with org:manage_settings who aren't Owners can view the settings, but not change them. They see: "Only an Owner can change single sign-on. Ask an Owner of this organization to do it." See Roles and permissions.
  • Owner means the Owner role in your Lingo.dev organization. Being an admin in Okta or Microsoft Entra ID doesn't give it. The identity provider admin sets up the app there, and a Lingo.dev Owner connects it.
  • Changing SSO is limited to Owners because whoever controls the identity provider can sign in as any member who uses SSO, Owners included.
  • Turning on Require SSO also needs an Owner who signed in through your identity provider. See Turn it on.
  • Sign in to Lingo.dev with a password, an email link or Google, using a confirmed email address at the domain you want to connect.
  • Your identity provider must support SAML 2.0.

Values for your identity provider #

Settings → SSO shows these values with a Copy button. They are the same for every organization.

Lingo.dev labelValueOkta fieldMicrosoft Entra ID field
Entity IDhttps://auth.lingo.dev/auth/v1/sso/saml/metadataAudience URI (SP Entity ID)Identifier (Entity ID)
ACS URLhttps://auth.lingo.dev/auth/v1/sso/saml/acsSingle sign-on URLReply URL (Assertion Consumer Service URL)
Service provider metadatahttps://auth.lingo.dev/auth/v1/sso/saml/metadataNot neededNot needed

Use the service provider metadata URL only if your identity provider can read these settings from a URL.

Once SSO is connected, Settings → SSO also shows a Dashboard sign-in link for your organization. It goes on a dashboard tile, not in the SAML app. See Sign in from a dashboard tile.

The SAML response must include the person's email address:

  • In Okta, set Name ID format to EmailAddress and add an email attribute statement.
  • In Microsoft Entra ID, apps created in the Entra admin center send an emailaddress claim and an email-format Name ID by default. An app created without the default claims, for example through the API, sends no email. Add the email claim (user.mail) in Attributes & Claims.

Connect your identity provider #

  1. In your identity provider, create a SAML app for Lingo.dev with the values above. Step-by-step guides: Okta and Microsoft Entra ID.
  2. Assign the people or groups who should use Lingo.dev.
  3. Copy the app's SAML metadata URL. It starts with https://.
  4. In Lingo.dev, open Settings → SSO.
  5. Paste the URL into Identity provider metadata URL.
  6. In Email domains, type your company's email domains, separated by commas. For example, example.com, eu.example.com.
  7. Select Connect.

Status now shows Connected since and the date. To test, open a private browser window and sign in as one of the assigned people, as described in How members sign in.

Domain rules #

  • Each domain must be the domain of your own email address, or a subdomain of it. If you sign in as jane@example.com, you can add example.com and eu.example.com, but not example.org. For another domain, ask an admin with an email address at that domain.
  • Free and disposable email providers, such as gmail.com or yahoo.es, are refused, and so are their subdomains. So is lingo.dev.
  • Members join only from a domain you added, matched exactly. Adding example.com doesn't cover eu.example.com: add each subdomain your members sign in from.
  • A company domain under a country's second-level registry is fine, such as acme.net.ua or acme.co.uk. The registry itself, such as net.ua, is refused.
  • A domain can belong to only one organization. If another organization already has it, email support@lingo.dev to move it.
  • A domain stays with your organization once added. You can't remove it, even after you disconnect.
  • Add new domains as an Owner signed in with a password, an email link or Google. An account created through SSO can't add domains.

Change the connection #

To add domains or change the metadata URL, edit the fields in Settings → SSO and select Save. Only an Owner can do this, and it needs the Enterprise plan.

One identity provider connects to one organization. To switch your organization to a different identity provider, or to move one from another organization, email support@lingo.dev.

When your identity provider rotates its signing certificate, open Settings → SSO and select Save without changing the fields. This reloads the metadata, with the new certificate, from the URL. Don't count on Lingo.dev to pick up the new certificate on its own. Until you select Save, sign-in can fail with "Single sign-on didn't complete".

How members sign in #

  1. On the Lingo.dev sign-in page, select Continue with SSO.
  2. Type your work email and select Sign in.
  3. Sign in on your company's sign-in page.
  4. You return to Lingo.dev as a member of the organization.

The email you type only finds your company's identity provider. Your identity provider decides who signs in. If the browser is already signed in there, it continues as that account, often without asking for a password. Lingo.dev then uses the email your identity provider sends.

Signing out of Lingo.dev doesn't sign you out of your identity provider. While that session lasts, the next Continue with SSO signs you straight back in.

The first SSO sign-in adds the person to the organization. No invitation is needed.

  • If your plan applies roles, they join with no role. Give them one in Settings → Team. See Team.
  • If roles aren't applied, they join as an Owner.

People added over SCIM join with their invite's role instead. See Provision members with SCIM.

The CLI (lingo login) and MCP clients open a Lingo.dev sign-in page that also has Continue with SSO.

SSO creates a separate account

The first SSO sign-in creates a new Lingo.dev account, even if the person already has a password, email link or Google account with the same email. The accounts are not merged. The SSO account doesn't get the old account's role, organizations or personal API keys.

Your team list can show the same email twice: once for the old account and once for the SSO account. Give the SSO account the role the person needs. Remove the old account when it's no longer needed.

Sign in from a dashboard tile #

Members can also sign in from a Lingo.dev tile on the Okta dashboard or in Microsoft My Apps. The tile must open the Dashboard sign-in link from Settings → SSO. It looks like https://lingo.dev/auth/sso?domain=example.com, with your first connected domain.

The link starts sign-in on Lingo.dev, so members don't type their email. They go to your identity provider and come back signed in, as with Continue with SSO.

Without the link, the SAML app's own tile doesn't sign you in. You land on the Lingo.dev home page, still signed out.

Require SSO #

When Require SSO is on:

  • People must sign in through your identity provider to open this organization.
  • Passwords, email links and Google stop working for this organization. People can still sign in that way, and their other organizations are not affected. Your organization shows Requires SSO in their list, and opening it asks them to continue with SSO.
  • Personal API keys created by accounts that didn't join through SSO stop working in this organization.
  • Organization service keys keep working across the Lingo.dev API. Use them for CI and other automation. See API keys.
  • An MCP client connected with an account that didn't sign in through SSO can't use this organization. Sign in with SSO, then reconnect. See MCP connection setup.

Turn it on #

Turning on Require SSO needs an Owner who signed in through your identity provider. Your SSO account is a separate account, and the Owner role of your old account doesn't carry over to it. Make it an Owner before you start.

  1. Sign in to Lingo.dev with Continue with SSO. This adds your SSO account to the organization.
  2. If your plan applies roles, the SSO account joins with no role. From your existing Owner account, make the SSO account an Owner in Settings → Team. If roles aren't applied, it already joined as an Owner.
  3. Signed in with the SSO account, open Settings → SSO and turn on Require SSO.

The switch stays off until you sign in through your identity provider. This keeps you from locking yourself out with a password session.

Turn it off #

An Owner can turn off Require SSO in Settings → SSO. People can open the organization with a password, an email link or Google again. You can turn it off even when your plan no longer includes SSO.

Keep a way in

While SSO is required, only SSO accounts can open the organization, including its settings. Keep at least one Owner who signs in through your identity provider. Lingo.dev won't let the last such Owner leave or step down. If your identity provider stops working, email support@lingo.dev.

Provision members with SCIM #

SCIM lets your identity provider decide who is a member of your organization. Assigning someone to the Lingo.dev app invites them, and unassigning them removes them. Groups set their role. People still sign in with SSO.

Setup guides: Okta and Microsoft Entra ID.

Before you set up SCIM #

  • SSO must be connected, which needs the Enterprise plan.
  • Only Owners see the SCIM key in Settings → SSO and can generate, rotate or revoke it.
  • The SCIM key acts with a role you pick. The role must include org:manage_team and can't be Owner. See Roles and permissions.
  • The key can set a role through a group only if its own role has every permission of that role.

Generate the SCIM key #

  1. Open Settings → SSO. SCIM base URL and SCIM key are below Require SSO.
  2. Next to SCIM key, pick the role the key acts with.
  3. Select Generate key.
  4. Copy the key and store it safely. Lingo.dev shows it only once. Then select I've stored it.
  5. Copy SCIM base URL: https://api.lingo.dev/v2/scim.

Your identity provider sends the key as a Bearer token to the base URL. The key works only for SCIM and isn't listed with your other API keys.

If no role can take the key, the role picker reads No role and Generate key stays off. Give a role other than Owner the org:manage_team permission first.

Assign people #

  • Assigning a person to the Lingo.dev app creates a pending invite in Settings → Team, on the Invitations tab. No email is sent, and the invite expires in 100 years.
  • The person becomes a member on their first SSO sign-in, with the invite's role.
  • If the person is already a member, SCIM links them to that membership instead of creating an invite.
  • SCIM accepts only email addresses at your connected domains. Your identity provider shows an error for anyone else.
  • People not sent over SCIM can still join on their first SSO sign-in. See How members sign in.

Set roles with groups #

  • Push a group with the same name as a Lingo.dev role, such as Translator, in any letter case. The group's members get that role, and removing someone from the group clears it.
  • A group never makes anyone an Owner, and it doesn't change an Owner's role. Manage Owners in Settings → Team.
  • A group whose name matches no role is refused with an error in your identity provider. Create the role in Lingo.dev first.
  • Each person has one role. If they are in several pushed groups, the last group pushed wins.
  • If you rename a role in Lingo.dev, groups you push later must use the new name. Groups already pushed keep setting that role.
  • If your identity provider deletes a pushed group in Lingo.dev, its members lose the role. The role itself stays.

Remove people #

Unassigning or deactivating a person in your identity provider:

  • removes their membership;
  • revokes their personal API keys in the organization;
  • revokes their pending invites to the organization;
  • stops SSO from adding them again, as long as the organization has a SCIM key.

A Lingo.dev session they already have open isn't ended, but it no longer has access to the organization. If they sign in with SSO again, they see "Your identity provider removed your access to your organization. Ask your IT admin to restore it if this is a mistake."

Owners can be removed this way too. For the last Owner, your identity provider shows an error.

Assigning or reactivating the person creates a new pending invite with no role. They get a role again when your identity provider pushes their group.

Rotate or revoke the key #

In the SCIM key setting, Rotate and Revoke both ask you to confirm.

  • Rotate creates a new key with the role you picked and revokes the old one at once. Provisioning fails until you paste the new key into your identity provider. Copy the new key before you close it.
  • Revoke stops your identity provider from adding, updating and removing members at once. Members already in the organization stay. People your identity provider removed can join again by signing in with SSO.

If a rotation couldn't revoke the old key, the setting shows "The previous SCIM key still works." Select Revoke to revoke only the previous key. The new key keeps working.

The audit log shows changes made over SCIM as made by the SCIM key.

Errors in your identity provider #

ErrorWhat to do
No role named (group) at /Groups. Create a role with that name in Lingo.dev, or push only groups named after a role.Create a role with the group's name, or stop pushing that group.
The Owner role at /Groups. Owners are managed in Lingo.dev; push a group named after another role.Groups can't set Owner. Make Owners in Settings → Team.
Email (address) outside the single sign-on domains at /Users. Provision addresses in (domains).Assign only people with an email at your connected domains, or add the domain in Settings → SSO.
No connected identity provider at organization (ID). Connect single sign-on again to resume SCIM provisioning.SSO was disconnected. Connect it again.
A plan without single sign-on at organization (ID). Upgrade the plan to resume SCIM provisioning.Check your plan in Billing.
401 UnauthorizedThe key was rotated or revoked. Paste the current SCIM key into your identity provider, or generate a new one.

SCIM limitations #

  • Lingo.dev doesn't show when the SCIM key was last used.
  • SCIM stops working while SSO is disconnected or your plan doesn't include SSO. Members stay as they are.
  • Google Workspace doesn't offer SCIM for custom SAML apps.

Disconnect #

Only an Owner can disconnect.

  1. Open Settings → SSO.
  2. Under Disconnect identity provider, select Disconnect.
  3. Confirm with Disconnect.

SSO stops for the organization, and it is no longer required. Members sign in with a password, an email link or Google again. Status shows Disconnected on and the date.

Memberships stay as they are. Your domains stay reserved for the organization, so you can connect again later: select Connect with the same identity provider. A different identity provider needs support@lingo.dev.

Accounts created through SSO lose access to the organization while SSO is disconnected, including sessions they already have open. Continue with SSO answers that single sign-on is not set up for the domain, and a password, email link or Google sign-in with the same email opens a separate account. These accounts stay members and get their access back when you connect the same identity provider again. No one joins the organization through SSO until you connect again. To keep working in the meantime, people need their own password, email link or Google account with its own membership. If you signed in through SSO yourself, you lose access too, so make sure another Owner signs in with a password, an email link or Google before you disconnect.

If your plan no longer includes SSO #

Your connection stays visible in Settings → SSO, with a notice. An Owner can still turn Require SSO off and disconnect. Connecting, changing the connection and turning Require SSO on need the Enterprise plan again.

Until you change something, SSO sign-in and Require SSO keep working as before.

Audit log #

SSO changes appear in the audit log, with the person who made them:

ActionShown asWhen
sso.connectedconnected single sign-onThe first connect, or connecting again after a disconnect
sso.updatedupdated single sign-onSave on a connected identity provider, for example with a new metadata URL or more domains
sso.enforcement_enabledrequired single sign-onRequire SSO turned on
sso.enforcement_disabledstopped requiring single sign-onRequire SSO turned off
sso.disconnecteddisconnected single sign-onThe identity provider disconnected

When a first SSO sign-in adds someone to the organization, it shows as "joined the organization".

Troubleshooting #

Sign-in messages #

MessageWhat to do
Type your work email. Single sign-on starts from its domain.Enter a full email address, such as you@example.com.
Your email isn't at a domain your organization uses for single sign-on. Sign in with a work email at your company's domain.Your identity provider signed you in with an email outside the organization's connected domains, for example a personal address or an unlisted subdomain. Sign in to your identity provider with your work account, or ask an Owner to add the domain.
Single sign-on is not set up for example.com. Sign in with a password, a link or Google.No connected organization uses that domain. Check the spelling, or ask your admin which domains are connected.
Could not check single sign-on for example.com. Try again in a moment.Lingo.dev couldn't look up the domain. Try again.
Single sign-on took too long to finish. Try again.The sign-in took longer than about 5 minutes, for example while your identity provider asked you to set up multi-factor authentication. Try again. The next attempt works.
Your identity provider didn't send an email address. Ask your IT admin to add the email attribute or claim to the Lingo.dev app.The SAML response has no email. See the Okta or Microsoft Entra ID guide.
Single sign-on didn't complete. Try again, or ask your IT admin to check the Lingo.dev app in your identity provider.Usually a wrong Entity ID or ACS URL in the identity provider app. Compare them with the values above.
You're signed in, but we couldn't add you to your organization. Try again, or ask your admin.Your SSO sign-in worked, but joining the organization failed. Sign in with SSO again. In the CLI or an MCP client, this shows on the connect screen; reload it to try again. If it keeps failing, ask an Owner to check that Settings → SSO shows Connected since.
This organization requires single sign-on. Sign in through your identity provider, then try again.You opened an organization with Require SSO from another kind of sign-in. Select Continue with SSO. If the email you're signed in with isn't your work email, select Use another work email.

Errors from your identity provider, such as Microsoft's AADSTS codes, appear on its own sign-in page. The provider guides cover the common ones.

Settings messages #

MessageWhat to do
Only an Owner can change single sign-on. Ask an Owner of this organization to do it.You can view SSO, but only an Owner can change it. Ask an Owner.
example.com is not your email domain.Add only your own email domain or its subdomains, or ask an admin with an email address at that domain.
gmail.com is a public email provider. Use a domain your company owns.Free and disposable email domains can't use SSO. Add the domain your company owns.
lingo.dev is reserved. Use a domain your company owns.Add the domain your company owns.
example.com already signs in through another organization's identity provider.Email support@lingo.dev to move it.
The identity provider's metadata was refused: (reason). Check the metadata URL.Copy the metadata URL again from your identity provider app. It must be a public https:// URL.
This metadata belongs to a different identity provider than the one connected.Switching identity providers needs support@lingo.dev.
This identity provider is already connected to another organization.Email support@lingo.dev to move it.
Sign in through your identity provider to turn this on.Sign in with Continue with SSO, then turn on Require SSO.
Requiring SSO comes with Enterprise.Check your plan in Billing.

Known limitations #

  • Only an account whose email is at one of your connected domains joins, and the domain has to match exactly. Your identity provider can still sign in others, such as a guest with a personal address or someone at a subdomain you didn't add. Lingo.dev signs them out again and shows why. Assign only the right people to the app in your identity provider, and add every subdomain your members sign in from.
  • Roles are not carried over from a person's earlier password, email link or Google account.
  • Removing someone in your identity provider doesn't end a Lingo.dev session they already have open. Lingo.dev doesn't check back with your identity provider during a session. With SCIM, the removal also ends their membership, so that session no longer has access to the organization. Without SCIM, the session keeps working until they sign out, so also remove them in Settings → Team.
  • If you remove a member in Lingo.dev while your identity provider still lets them in, they join again on their next SSO sign-in, with or without SCIM. With SCIM, remove them in your identity provider instead; that also removes their membership and keeps them from joining again. Without SCIM, remove them in your identity provider first, then in Settings → Team.
  • A dashboard tile signs you in only when it opens the Dashboard sign-in link. The SAML app's own tile in the Okta dashboard or Microsoft My Apps lands you on the Lingo.dev home page, still signed out. See Sign in from a dashboard tile.
  • You can't remove a domain or switch identity providers yourself. Email support@lingo.dev.