Skip to content
Esc
↑↓navigate↵open⌘Jpreview
On this page

SSO and Directory Sync

Set up single sign-on for an API Platform organization: verify your domain, connect your identity provider, and understand how people sign in and join.

Single sign-on (SSO) lets the people in your company sign in to QuiverAI with the accounts your company already manages, through your identity provider (IdP), such as Okta, Microsoft Entra ID, or Google Workspace. QuiverAI connects to your IdP with SAML or OpenID Connect (OIDC), the two standard protocols for this. This page is for the Owner or Admin who sets it up and for the IT administrator who configures the IdP.

SSO is offered to organizations on an enterprise agreement. It works on its own. Directory Sync, which keeps members and roles in step with your company directory, is an optional addition that you connect from the same page.

Before you start

  • You must be an Owner or Admin of the organization in the API Platform. Only Owners and Admins can open Identity under Settings.
  • QuiverAI must turn SSO on for your organization. Contact sales or your account team. Until it is on, the Identity page explains single sign-on and offers Contact sales, and nothing else.
  • You need access to your IdP and to your domain’s DNS records, or an IT administrator who has both.

What turning on SSO changes

Once the connection is active, everyone with an email address on your verified domains must sign in with SSO. This applies to both the API Platform and the App at app.quiver.ai, and it applies to every such person whether or not they are already a member of your organization.

  • Their other sign-in methods, such as Google or an email code, stop working for those addresses.
  • There is no separate switch to enforce SSO or to relax it later. An active connection enforces it.
  • People you invite with an email address outside your verified domains are not affected and keep signing in as they do today.
  • Existing API keys keep working. Keys belong to projects, not to people, so activating SSO does not revoke any.

Because of this, verify your domain, configure the connection, then confirm it with one sign-in, before you announce SSO to employees.

Set up the connection

Open the Identity page

Go to Identity under Settings. While SSO is not live, the Set up single sign-on panel at the top walks you through two steps: Verify your email domain and Connect your sign-in provider. Select a step to open it. Once SSO is live, the page shows a status strip and the Domains, Sign-in and Joining sections instead.

Verify your domain

In Verify your email domain, select Add domain. Enter your company’s email domain, such as example.com, in the setup page that opens. QuiverAI then shows the DNS TXT record to add (its Type, Host and Value, each with a copy button) right under the domain. Add it at your DNS provider. If WorkOS asks for a record format QuiverAI cannot show, the domain shows Verify domain instead, which opens the setup page with the record to add. A verified domain is one you have proven you own. Public email domains such as gmail.com cannot be verified, and a domain can belong to only one organization.

Wait for the domain to verify

DNS changes can take a while to show up, usually within an hour and up to 48 hours. The domain shows Waiting for DNS until WorkOS finds the record, and the page updates on its own once it does; there is nothing to select. Leave the record in place while you wait. The domain then shows Verified. If the record isn’t found within 30 days, the domain shows Verification failed; select Fix to open the setup page, correct the record so it matches the one shown, and restart verification there. When the first domain verifies, the step shows a check mark.

Connect your sign-in provider

Select Connect sign-in provider at the bottom of the first step. You can connect a provider before your domain is verified; single sign-on starts working once both are done. A dialog titled Turn on single sign-on? first explains that SSO will apply to everyone on your verified domains; choose Continue. On the setup page you pick Okta, Microsoft Entra ID, Google Workspace or another SAML or OIDC provider, and it gives instructions for each. When you finish, you come back to the Identity page, where the second step shows your connection. See the WorkOS Admin Portal documentation if your IT administrator needs more detail. Once a connection exists, its button reads Manage.

Sign in with SSO once

The connection is not proven until someone has an SSO sign-in through it, even one refused for membership. Until then its row under Sign-in reads Not tested yet. Click those words to copy a test sign-in link that signs in through that connection. Open the link in a private window and sign in with your work account. After that sign-in, the row reads SSO tested with the time, such as SSO tested 2 minutes ago. The page remembers only the connection tested most recently, so if you have several active connections, testing one moves SSO tested to it and the others read Not tested yet again. This counts even if you were not let in to the organization, because the sign-in itself worked.

Domains and provider connections are set up on a hosted page built for IT administrators, so the buttons that open it, such as Add domain, Connect, Manage and Fix, are also where you go for help with your DNS provider or to remove a domain. The link is generated when you ask for it and expires after five minutes. If it expires, or you hand the task to your IT administrator, open it again from the Identity page. QuiverAI never emails it.

Status

While you are setting up, the panel shows Step 1 of 2 or Step 2 of 2 and marks finished steps Done. Once SSO is live, the status strip at the top of the page reads On, Needs attention or Off:

State Meaning
On People on your verified domains sign in with your provider. The strip names the domains and provider.
Needs attention A domain is unverified, the SSO connection is inactive, or your company directory can’t sync. The strip names the problem and offers a fix.
Off SSO isn’t set up. Add a domain to get started.

Domains shows a status for each domain (Verified, Waiting for DNS or Verification failed), and Sign-in shows one for each connection (Active, Draft, Inactive or Validating). Status is read live. While a domain is pending or a connection is untested, the page re-reads it on its own, every 30 seconds for a pending domain and when you come back to the tab. The setup panel gives way to the status strip as soon as a domain is verified and a connection is active, which does not prove that signing in works. Confirm it by signing in with an account on your domain: the connection’s row under Sign-in reads Not tested yet until someone does. If your organization has a company directory, it also appears in step 2 while you set up, with its warning underneath. If you later remove every domain and every connection, the page returns to the setup panel.

How people sign in

In the API Platform, people enter their work email address and choose Continue with email; an address on a verified domain goes straight to your IdP. In the App, they choose Send code and enter the code they receive, and are then sent to your IdP. There is no separate SSO button. Starting from the QuiverAI tile in your IdP dashboard works too.

Joining and roles

Joining on the Identity page sets how people on your verified domains join without an invite. It has two rows, and a connected directory takes precedence over the second:

Row What it does
Company directory Your connected directory decides who joins and in which role. With no directory it reads (optional) and offers Connect.
Auto-join from verified domains A switch. Off, only people you invite can join; this is where new organizations start. On, anyone with an email on a verified domain joins without an invite, with the Joins as role.

While a directory is connected, the auto-join row is hidden and your directory decides who joins. An Owner or Admin changes these settings, which needs the SSO entitlement, and each change appears in the audit timeline.

Organizations that had finished SSO setup, or had turned on joining by email domain, before Joining existed started with auto-join on. Every other organization started with it off.

Auto-join off

A person who signs in with SSO and is not yet a member is refused. They see “You signed in with SSO, but you aren’t a member of this organization yet. Ask an admin of the organization or your IT admin to add you.” Invite them, and they join with the invited role as for anyone else. Someone on a verified domain who signs in with Google or an email code and has no organization is asked to get an invite from an Admin of your organization. Your organization’s name is not shown to them.

Auto-join on

When someone on a verified domain signs in with SSO and is not yet a member, QuiverAI adds them automatically. This is called just-in-time (JIT) provisioning.

  • They join with your organization’s default role for new members, which starts as Developer. A Developer or Viewer also gets access to the Default Project.
  • Turn on Auto-join from verified domains to show Joins as. Choose Admin, Developer or Viewer; choosing Admin asks you to confirm with Make Admin the default. The change applies to people who join after it; existing members keep their role.
  • SSO never makes anyone an Owner.
  • An Admin can change their role and project access afterward on the Organization page.
  • Invites still work. If someone joined automatically and then opens an invite, the invited role and project access apply, as long as nobody has changed their role or access since they joined. An invite to Viewer leaves their role and access unchanged while they still hold API keys; an Admin changes it once the keys are reassigned or revoked.

Auto-join also covers people who do not use SSO, even before your connection is active:

  • Someone who signs in with Google or an email code, has no organization yet, and has an address on a verified domain is offered Join with your organization’s name. They join in one step, with the default role, as SSO joins do.
  • Once your connection is active, people on your verified domains sign in with SSO and join through JIT.

Company directory

While a directory is connected, Company directory reads “Members and roles come from” your provider, the auto-join row is hidden, and your identity provider decides who joins. If you disconnect the directory, the auto-join choice you made before applies again. With no directory connected, Company directory shows Connect, so your IT admin can set it up.

Removed members

People who were removed from the organization, or who left it, are not added back by SSO or by joining with an email domain, in any option. They are asked to contact an Admin. An Owner or Admin can bring them back by selecting Restore on the Removed tab of Members on the Organization page, or by sending a new invite.

People with a verified-domain address can’t create separate organizations, so company usage stays in yours. Personal organizations they created before verification stay as they are; QuiverAI never moves or deletes them. To bring that work into your organization, invite the person, create new API keys in your organization’s projects, and have them delete their personal organization when it is no longer needed.

Guests and contractors

Invite people whose email is outside your verified domains. They sign in with Google or an email code, as before.

Removing access

Disabling someone in your IdP stops their next SSO sign-in. It does not end a session they already have open. Without Directory Sync, to remove access immediately, also remove them from the organization on the Organization page. Their API keys are not revoked either way, because keys belong to projects.

Directory Sync

Directory Sync connects your IdP’s directory, so members and roles follow your company’s groups instead of manual invites and edits. It is part of the same enterprise agreement as SSO, and you can run SSO with or without it.

Connect a directory

An Owner or Admin connects a directory from Joining on the Identity page.

  1. Select Connect on the Company directory row. A setup page opens. It is the same hosted page that SSO setup uses, so you can hand it to your IT administrator.
  2. On that page, connect your IdP’s directory, choose the groups to sync, and map each group to a role.
  3. Return to the Identity page. Company directory shows the directory and its state. Once a directory exists the button reads Manage, or Fix if it can’t sync.

QuiverAI does not configure SCIM, the standard protocol directories use to sync, for you. The setup page does that. The link is generated when you ask for it, expires after five minutes, and is never emailed.

The state is read live each time the page loads:

State Meaning
Connected The directory is syncing members.
Validating QuiverAI is checking the connection. Wait a moment and reload.
Can’t sync Your directory can’t be reached or isn’t syncing. Select Fix to see why.
Being deleted The directory is being deleted.

If no directory is connected, the row reads Company directory (optional) and offers Connect.

Review members who are not in the directory

While a directory is active, members who joined before it and sit on one of your verified domains, but are not managed by the directory, are labelled Not in directory on the Members tab of the Organization page. Invited guests outside your verified domains and Owners are never listed.

The Organization page also points you to them. When something in your directory needs attention, an alert above the members list says, for example, “4 directory items need attention.” with an Open Identity button. Only Owners and Admins see it.

Nothing removes these members automatically, because WorkOS does not tell QuiverAI when the first full sync is done. Check the list against your directory first. Then Owners and Admins can remove everyone listed in one step from the warning under Company directory in Joining on the Identity page, for example “3 members aren’t in your directory”:

  1. Select Review.
  2. Read the dialog, Remove N members not in your directory?, and select Remove N members. They lose access right away, and the API keys they own move to you, so production keeps working. Your directory can add them back.

The removal acts on exactly the members you were shown. If someone stops qualifying in the meantime, for example because the directory added them, they stay, and QuiverAI tells you how many stayed. You are never removed by this action. You can restore removed members from the Removed tab on the Organization page.

The warning appears only while there is something to review. A review lists up to 500 members at a time; if there are more, remove these, then review again for the rest.

If the directory removes your only Owner

The directory never removes the last Owner of an organization. When it tries, the member keeps their seat and the warning under Company directory on the Identity page says “1 needs a fix”; Review names the member. Contact QuiverAI support to hand ownership to another member, from a channel QuiverAI already knows for your organization.

If a group maps to a role QuiverAI does not know

If a directory group gives someone a role other than Admin, Developer or Viewer, the warning under Company directory counts them as needing a fix, and Review names the person and the role. Their seat stays as it is. Map the group to Admin, Developer or Viewer in your directory settings.

Roles from groups

Planned: directory groups map to Admin, Developer, or Viewer. The directory never grants or changes Owner. Someone whose groups map to any other role, including the WorkOS default role, is not added or changed, and QuiverAI is alerted. New Developers and Viewers get access to the Default Project.

Managed members

While a directory is active, members it manages carry a Directory badge on the Organization page, and their controls read Managed by your company directory. Their role and their removal belong to your IdP: QuiverAI refuses to change their role, remove them, or let them leave, on the Organization page and through the API alike. Change their groups or unassign them in your IdP instead, and QuiverAI follows. Project access stays editable for everyone, and members you invited who are not in the directory stay fully editable.

Ownership is the one exception, because the directory never grants or changes Owner. An Owner can make a managed member Owner. An Owner can also take the Owner role away from another managed member by choosing Role from your company directory: QuiverAI reads the role your IdP assigns them right away and applies it. If your IdP gives them no role QuiverAI can use, nothing changes and you are asked to check their groups.

Removal

Planned: removing someone in the directory removes their access and ends their sessions. API keys they own are reassigned to your longest-standing Owner, not revoked. The directory cannot remove the last Owner. Adding them back gives them a fresh membership, without the project access they had before.

People outside your directory groups

Directory Sync covers the people in the groups you map to roles. Anyone else who signs in with SSO, such as guests, contractors, or an Owner your directory does not hold, still needs to be assigned to the QuiverAI app in your IdP on their own. In Okta, open the app, choose Assignments, and assign them as a person. An assignment that exists only through a group you map to a role ends when the person leaves that group, and their sign-in fails until they are assigned to the app directly.

Joining and disconnecting

Planned: automatic JIT joining stops while a directory is active, and your Auto-join from verified domains choice has no effect until you disconnect it. Someone you add in the directory can sign in with SSO right away, without waiting for the next sync. Someone the directory does not include is refused unless you invite them. If you disconnect the directory, members keep their access, become editable again, and your earlier choice applies again.

Troubleshooting

“Single sign-on isn’t set up for this email domain. Use another sign-in method.” The address is not on a verified domain with an active connection. Check the domain and connection statuses on the Identity page.

“Your organization can’t use SSO right now. Ask your IT admin to check its SSO setup.” The organization’s SSO setup has a problem. An Owner or Admin should check the Identity page and the IdP configuration.

One person cannot sign in. Their IT administrator should check that the person is assigned to the app in the IdP and that their IdP email is on a verified domain.

Everyone is locked out because the IdP is broken. An Owner or Admin contacts QuiverAI support from a channel QuiverAI already knows for your organization, such as your account team, since company email may be affected too. Support can deactivate the connection, which restores the other sign-in methods. Then repair the connection from the Identity page and sign in with SSO again.

Open Identity

Verify your domain, set up SSO, connect a directory, and choose how people join.

Was this page helpful?