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, then configure and test the connection, before you announce SSO to employees.

Set up the connection

Domains are added, verified and removed only in the Admin Portal, so Add or edit domains is also where you go for help with your DNS provider or to remove a domain. QuiverAI shows no DNS record of its own. The Admin Portal 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

The Set up single sign-on list marks each step Done or Next. Domains shows a badge for each domain (Verified, Waiting for DNS or Verification failed), and Single sign-on shows one for the connection (Active, Draft, Inactive or Validating). Status is read live when the page loads, so reload it to read it again. Setup is complete, and the list goes away, only after the first successful SSO sign-in.

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

How people join on the Identity page sets how people on your verified domains join without an invite. An Owner or Admin chooses one option:

Organizations that had finished SSO setup, or had turned on joining by email domain, before How people join existed started on Automatic. Every other organization started on Invite only. The choice needs the SSO entitlement, and each change appears in the audit timeline.

Invite only

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.

Automatic

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.
• Select Automatic to show the default role. Choose Admin, Developer or Viewer. 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.

Automatic 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 is selected, the other two options are off, and your identity provider decides who joins. If you disconnect the directory, the choice you made before applies again. With no directory connected, Company directory is off and shows Connect directory, so your IT admin can set it up in the Admin Portal.

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 How people join on the Identity page.

1. Select Connect directory under Company directory. The WorkOS Admin Portal opens. It is the same hosted page that SSO setup uses, so you can hand it to your IT administrator.
2. In the Admin Portal, 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, and is selected once the directory is active. Once a directory exists the button reads Manage directory.

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

The state is read live from WorkOS each time the page loads:

If no directory is connected, the row says No directory connected.

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 Needs attention section of the Identity page:

1. Select Review N members.
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 Needs attention section 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 Needs attention section of the Identity page says so. 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 Needs attention section of the Identity page names the person and the role, and 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 Automatic or Invite only 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 badges 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 in the Admin Portal and sign in with SSO again.