SSO, SCIM & Domain Verification

An organization admin on the Enterprise plan configures identity from the dashboard. People & Access → Organization (page title Organization) includes a Compliance card, Require compliance records, above the identity cards. The three identity cards are unchanged: each of their buttons opens the WorkOS Admin Portal in a new tab and, when you finish, returns you to that same organization page.

We recommend this order: verify the domain, connect SSO, then turn on Directory Sync. Corveil does not require a verified domain before you connect SSO. The requirement comes from WorkOS, for just-in-time membership: someone whose email is on a verified domain joins the organization when they first sign in, and anyone else has to be invited first.

Card	Button	What it does
Domain verification	Verify domain	Prove you own an email domain with a DNS TXT record.
Single Sign-On	Configure SSO	Connect SAML or OIDC to your identity provider.
Directory Sync (SCIM)	Configure SCIM	Provision and deprovision members from that directory.

The identity providers the portal offers include Okta, Microsoft Entra ID, and Google Workspace. Pick yours in the portal; it shows the provider-specific steps.

Prerequisites

You open this setup as an organization admin (owner or admin) from People & Access → Organization. On that page, Verify domain, Configure SSO, and Configure SCIM stay disabled until the organization is on the Enterprise plan and linked to WorkOS. One plan check covers all three.

Enterprise plan. When the plan does not include this setup, each card says Available on the Enterprise plan. A portal request from that organization is rejected with Self-serve SSO requires the Enterprise plan.

Linked to WorkOS. When the organization has no WorkOS link yet, each card says Available once this organization is linked to WorkOS. A portal request for an unlinked organization is rejected with Organization is not linked to WorkOS.

When the buttons are enabled, click one. The Admin Portal opens in a new browser tab.

Domain verification

Claim the email domain people will use to sign up, before you connect SSO.

1. Open People & Access → Organization.
2. On the Domain verification card, click Verify domain.
3. In the Admin Portal, add the DNS TXT record it gives you at the DNS host for that domain. Leave the record in place. The portal confirms the domain once DNS resolves.

How to tell it worked. Go back to the organization page. Focusing that browser tab refreshes domain status. The card lists the domain with a green Verified tag.

Until then, the card says No email domain is claimed for this organization, or it lists the domain as Not verified. Domain status is unavailable. Reload the page to try again. means the lookup failed for this request; reload the page.

Once the domain is claimed, a later signup from that domain joins this organization as a member.

Single Sign-On

Connect the identity provider so members of this organization sign in through it.

1. On the same organization page, open the Single Sign-On card.
2. Click Configure SSO.
3. In the Admin Portal, create a SAML or OIDC connection and finish the steps it shows for your provider (metadata, ACS or redirect URL, and the matching settings in the identity provider).

How to tell it worked. A member signs in and is sent to that identity provider, then lands in this organization.

Directory Sync (SCIM)

Keep membership in step with the directory. A provision creates the user and links them to the organization's default team. A deprovision archives the user, takes them off every team in the organization, and revokes their active virtual API keys. Their membership record is kept, role included, so provisioning the same person again reactivates it.

1. On the same organization page, open the Directory Sync (SCIM) card.
2. Click Configure SCIM.
3. In the Admin Portal, turn on directory sync and finish the SCIM steps your identity provider shows, using the endpoint and token the portal provides.

How to tell it worked.

• Provision someone in the directory. They show up on People & Access → Users, and on People & Access → Teams they are on the team named default. If a Group → Team rule matches one of their directory groups, they also appear on that directory-managed team. If a Group → Team role rule matches, they hold that role on the team. If a Group & attribute → Role rule matches, that Corveil role is re-applied on every sync; a protected owner is not demoted or removed.
• Deprovision that person in the directory. They are archived, and on People & Access → Teams they are no longer on any of the organization's teams. Virtual API keys that belonged to them stop authorizing gateway requests.

Directory sync leaves a protected owner in place. Role assignment still resolves inside Corveil; see Roles & Permissions.

Directory mappings

Once Directory Sync is on, you decide what a directory group means inside Corveil. People & Access → Directory Mappings (page title Directory Mappings) is one admin page with three sections:

Section	Maps	To
Group & attribute → Role	an IdP group name, or a value of the corveilRole attribute	a Corveil org role (member, viewer, gateway user, billing admin, budget viewer for all teams, admin)
Group → Team	a directory group	a Corveil team, created and kept in sync automatically
Group → Team role	a directory group	a team role — Budget viewer or Team admin — on one directory team

Mappings apply only through Directory Sync (SCIM): as people are provisioned, as their groups and attributes change, and on a periodic reconciliation. Signing in with SSO never reads them, so an attribute in the SAML sign-in assertion does not assign a role or a team.

The page is admin-only (owner or admin). It is not limited by plan, so you can still review and remove mappings after a downgrade. The mappings do nothing until Directory Sync is connected, which needs the Enterprise plan (see Prerequisites), and team mappings also need the WorkOS link.

Only groups you map are synced

Nothing syncs by default. A directory group affects Corveil only once you add a mapping for it, so your identity provider's hundreds of groups never become hundreds of Corveil roles or teams. Adding a mapping is opting that one group in; removing it opts it back out.

Group & attribute → Role

Click Add role mapping to add rules that assign an org role from a group or an attribute. Rules are ordered, and the first matching rule wins — put your most specific rules at the top and use the up/down controls to set precedence. A group rule matches the group's display name. An attribute rule matches a value of the corveilRole attribute.

A person with no matching rule keeps their current role — sync never resets an existing member; a rule is only ever applied to change a role, so removing someone from their only mapped group leaves their role as it was. A brand-new membership with no matching rule is created with the default role (member). owner is never a mapping target — ownership is managed by hand. When a rule does match, the mapping is the source of truth on each sync, so it can promote or demote a member — except it never demotes the organization's last admin, and it never changes a protected member.

The Budget stakeholder role is retired, so a new rule can't pick it. A rule that already targets it keeps working, and the page marks it Retired role. To convert it, point the rule at Viewer and add a Group → Team role rule that makes the group Budget viewer on each team it should see. Nobody loses access in the meantime.

The corveilRole attribute

Corveil defines one directory attribute for roles, named corveilRole, the same for every organization. You don't choose or type that name. Set it up in two places:

1. Once, in the Directory Sync portal. On People & Access → Organization, click Configure SCIM and map one of your own directory fields onto corveilRole. Where that field lives depends on your identity provider. In Google Workspace, for example, it can be a custom attribute such as Corveil → Role.
2. In Corveil, one rule per value. Click Add role mapping, choose corveilRole attribute, enter the value, and pick the role it means. For example, viewer → Viewer.

A person's field can hold more than one value. Each value is checked, and the first rule in the list that matches any of them wins. A value can't contain a colon (:); that form is reserved for team-scoped values.

Rules on another attribute name, added before the name was fixed, still apply. The page marks them Not corveilRole and doesn't let you edit them. To change one, add a corveilRole rule for the value and remove the old rule.

Group → Team

Add a group and Corveil provisions a directory-managed team for it and keeps that team in step with the group:

• The team roster follows the group. Everyone in the group who is in the organization is on the team, in addition to default; someone in several mapped groups is on each of those teams. Directory sync adds people with the team role User, unless a Group → Team role rule gives them a higher one. Two people are left out: a protected user is never moved by directory sync, and someone not yet provisioned into the organization joins the team once their account is provisioned.
• Spend counts against the group's team. A person's chat and session usage, and any API key with no team, counts against their primary team: their oldest team other than default where they're a User or Team admin. default is used only when they have no other team. Their Default API key is bound to their directory team when they're on exactly one, so its usage counts there too. A key they already had on default moves there on the next directory sync or periodic reconciliation. If they later leave the group, that key stays on the team; their other usage moves with them. Someone in several mapped groups keeps the Default API key on default, so an admin creates a key bound to each team that person should spend against. A key bound to a team always counts against that team, so a spend limit on a directory-managed team caps the group's usage.
• Keyed on the group's stable id, not its name. Renaming the group in your IdP renames the Corveil team but keeps it bound to the same group. (A rename does not update a group → role rule, which matches on the name — edit that rule's group name yourself after a rename.)
• The team is created on the next sync. A new mapping shows Awaiting sync until directory sync provisions its team, then Provisioned.
• Deleting the group archives the team (it is hidden, not destroyed, so history and any spend limit survive). The team is bound to the group's stable id, so the same group coming back reactivates that same team — but a group you delete and re-create in your IdP is a new group with a new id, even under the same display name. Nothing picks up the new group until you add a team mapping for it, which then provisions a fresh team; the archived team and its spend limit stay on the archived record until you delete it.

A missed or out-of-order webhook is self-healing: a periodic reconciliation re-converges each managed team and its membership against the directory, so the teams settle without any action from you.

Team mappings need a WorkOS-linked directory. Until Directory Sync is connected, the card says No directory connected and points back to Configure SCIM on People & Access → Organization. The Add team mapping button stays disabled until then.

Team roles from your directory

The Group → Team role section lets a directory group assign a team role on one directory-managed team: members of the group become Budget viewer or Team admin there. Pick a group, a directory team from the same directory, and the role. One group can grant a role on several teams, such as a Finance group that is Budget viewer on Sales and on Marketing.

Name your groups so the convention is obvious. Use one group per team (the roster) and one per team role you need on it:

Group	Directory Mappings rule
corveil-sales	Group → Team: the Sales team
corveil-sales-budget-viewers	Group → Team role: Sales, Budget viewer
corveil-sales-team-admins	Group → Team role: Sales, Team admin

How it behaves:

• A role group also puts people on the team. Someone in corveil-sales-team-admins but not in corveil-sales is on Sales, as Team admin.
• The highest role wins. User < Budget viewer < Team admin. Someone in both role groups is Team admin.
• The directory owns the roles on that team. Once a team has at least one role rule, every member's team role comes from the directory. A Team admin set by hand who isn't in a Team admin group goes back to User on the next sync. Before you save the first role rule on a team, Corveil lists the team's current Team admins so you can add them to the group first. A team with no role rule keeps the roles you set by hand.
• Leaving a group takes the role away. Leaving the Team admin group sets someone back to User (or Budget viewer, if they're in that group). Leaving every group of the team takes them off it.
• Only directory teams. A role rule targets a team made by a Group → Team rule in the same directory. Removing that team's Group → Team rule (detaching it) removes its role rules too, and its roles become hand-set.
• A lapsed plan never adds a role. If the organization loses the Enterprise plan, Directory Sync still removes roles and people, but doesn't grant new ones.
• A Budget viewer's own spend stays with their team. Joining a Budget viewer group doesn't change which team a person's own unattributed usage counts against. It stays on their oldest team other than default where they're a User or Team admin, or on default if that's the only one.

Changes arrive with your identity provider's sync, and a periodic reconciliation repairs anything missed. If Corveil can't read one of a team's groups, it changes no one on that team until it can.

Setting up the groups

The groups reach Corveil through Directory Sync, so create them in your identity provider and make sure they're provisioned to the Corveil app.

• Okta. Create one group per team and one per team role you use. Push them to the Corveil app with Push Groups. Okta doesn't allow one group to be used for both app assignment and Push Groups, so assign the app through a broad group, such as corveil-users. Okta has no nested groups, so add people to each group directly.
• Microsoft Entra ID. Create security groups and add them under the enterprise app's Users and groups. Keep provisioning on Sync only assigned users and groups. Entra provisions only direct members, so put people in the group itself, not in a nested group. Give each group a unique display name.
• Google Workspace. Create Google groups with direct members, and select them in the WorkOS directory's group filter. Google changes reach Corveil on WorkOS's roughly 30-minute Google sync.

Then add the mappings on People & Access → Directory Mappings: a Group → Team rule for each roster group, and a Group → Team role rule for each role group.

Keeping a manual edit — protection and detaching

Because a managed team is reconciled on every sync, a manual change to its name or membership is overwritten on the next sync. Two controls opt out:

• Protect a team (on People & Access → Teams) to freeze it. A synced team shows a Directory-managed tag; once protected it also shows Protected. Directory sync makes no change to a protected team — no rename, no membership or team-role change, no archive-on-delete — until you Unprotect it. Use this to hand-curate a directory team while keeping the mapping in place.
• Remove the team mapping to detach the team: it stops syncing and survives as an ordinary manual team, with its current members kept. Detaching is permanent; re-adding the group later provisions a fresh managed team.

Deleting archived teams

Directory sync never deletes a team; it archives it. To remove an archived team for good, open People & Access → Teams and click the delete icon on the inactive team. Corveil first shows what is attached:

• Users on the team are taken off it. Their accounts aren't affected.
• Spend limits for the team are deleted with it.
• Pending invitations no longer add people to the team. The invitations still stand.
• The team's Directory Mappings entries — its Group → Team rule and any Group → Team role rules — are removed, so those groups stop syncing to it.
• API keys bound to the team block the delete. Delete them on the API Keys page first.

Request logs and usage totals keep their numbers. An active team can't be deleted; deactivate it first.

This is how you clean up after reconnecting a directory. Deleting and re-creating SCIM in WorkOS creates a new directory, and its groups have new ids. The old directory's teams stay archived and keep their names, so a new team for a group with the same name gets a suffix, like Founders (…). Delete the archived team and the new team takes the plain name on the next sync.

Roles and teams are independent

A user holds one organization role and can be on any number of teams. On each team they also have a team role: User, Budget viewer, or Team admin. The two are separate settings:

• The organization role (for example Member or Viewer) decides what the user can do across the organization, on every team they are on. A team role never replaces it.
• Budget viewer lets them view that team's budget. Team admin lets them view and change it and read that team's request logs. Neither grants anything on another team.

A single group can carry an org role rule, a team mapping, and team role rules — the org role and the team axis never interact. Mapping a group to an org role does not create a team or change anyone's team role, and a team or team role mapping does not change anyone's organization role. The default team is the one exception that follows the org role: an org admin is its Team admin, and demoting an org admin through a mapping sets them back to User there. Other roles on the default team are left as they are. See Roles & Permissions for what each organization role can do.