Directory Sync (SCIM)

​

Overview

Directory Sync connects your identity provider’s user directory to Xenia over SCIM 2.0, so Xenia reads the list of people your IT team already maintains instead of asking you to upload it. It works with or without single sign-on. Like SSO, it is built on WorkOS — Xenia never speaks SCIM to your IdP directly, and any directory provider WorkOS supports works the same way from Xenia’s side — Okta, Microsoft Entra ID and Google Workspace among them, plus generic SCIM 2.0 for anything that speaks the protocol. WorkOS maintains the current provider list; adding one needs no change in Xenia. Connecting a directory does not create Xenia accounts. It gives you a mirror of the directory you can read and filter. You then write invite rules that decide who from that directory gets a Xenia account, what role and locations they land in — and press send when you’re ready.

​

Who can configure it

The Manage Directory Sync permission, granted to the Owner and Admin roles by default. An admin without it sees no Directory Sync item in Settings.

​

Connecting a directory

1. Go to Settings → Directory Sync. With no directory connected yet, you’ll see a Connect directory action.
2. That opens a WorkOS-hosted setup portal in a new tab. Everything IdP-side happens there — you’ll be given a SCIM base URL and a bearer token to paste into your identity provider’s provisioning configuration, along with provider-specific instructions.
3. Complete the steps in your IdP, then return to Xenia. The page picks the connection up on its own; there is no “check again” button to press.

Once linked, the page shows the provider, the connection state, how many users Xenia has mirrored, and when it last synced.

​

How syncing works

Xenia keeps a local mirror of your directory rather than calling your IdP on every page load. Three things keep it current, all automatic: A Sync now action on the page triggers a reconcile immediately if you don’t want to wait.

​

Invite rules

A rule is a set of conditions on directory attributes plus the role and location anyone matching it should get:

When groups contains IT → invite as Admin, scoped to Lake City

Rules are ordered, and evaluated top to bottom — the first match wins. Someone matching two rules gets the higher one’s role, not both. Anyone matching no rule is left uninvited and gets no access, deliberately: there is no fallback role on this path, because a fallback would mean emailing your entire directory. Conditions combine with All (AND) or Any (OR), and compare case-insensitively using is, is not, contains, does not contain, or starts with.

​

What you can write rules against

Everything your provider actually sends, including the structured fields: Multi-valued attributes are matched per value, not against a joined string — someone in both Engineering and IT matches a rule looking for either, and does not match one looking for Engineer as a substring of the concatenation.

​

Sending invites

Two ways, and both create Xenia accounts — this is an import, not a request queue:

• From the rules. Everyone matching an active rule who doesn’t already have an account.
• By hand. Tick people in the directory user list and invite just them, choosing the role and locations for that selection. No rule needs to exist.

​

Which email each person gets

The recipient’s email domain decides. There is no per-invite choice, deliberately — offering one would let an admin promise SSO sign-in to someone whose domain cannot use it:

​

Pacing and idempotency

• A mailbox can only be claimed once per workspace. Pressing send twice does not produce a second email; the second press claims nothing and leaves no trace.
• Sending is paced at 500 emails per hour. A 10,000-person directory therefore drains over about three days rather than in one blast, which keeps your domain’s sending reputation intact and gives bounce signal time to accrue.
• A failed invite can be retried. Failures stay in the log with their reason and are re-armed the next time you send, so a recipient who failed once is not stranded.
• Sending can be paused for a workspace by Xenia — for example if a large send starts bouncing heavily. Pausing stops the drain without discarding what is already queued; it resumes where it left off. There is no self-service pause control in the web app today.

​

Reading the results

The invite log shows every mailbox Xenia has claimed, its status, the role and locations it was sent with, and the failure reason where there is one — so “9,842 sent / 570 failed” is a real count rather than an assumption.

​

Seats

Invites are subject to your workspace’s user-seat limit. If a send would exceed it, Xenia refuses the whole send up front and tells you the shortfall, rather than creating accounts until the limit is hit and failing the remainder.

​

Directory Sync alongside SSO and HRIS

These three overlap, and it’s worth being clear on which does what: Directory Sync and SSO are independent add-ons that complement each other. Directory Sync gets people accounts with the right role and locations before they ever sign in; SSO is one of the ways they then get in. Using SSO alone means the first person through the door lands on the default role with no locations — see just-in-time provisioning. Using Directory Sync alone is perfectly fine: everyone gets the standard invite and sets their own password.

​

Known limitations

• No deprovisioning on sync. Removing or deactivating someone in your directory marks them removed in the Xenia mirror but does not deactivate their Xenia account or revoke their access. Offboard them in Xenia, via the web app or the Deactivate User API. Relying on the IdP side alone leaves an active Xenia account behind.
• No continuous auto-provisioning. Invites are sent when you press send; a person added to your directory tomorrow appears in the mirror automatically but is not invited until you send again.
• No automatic group-to-role mapping. Xenia does not read a WorkOS group-to-role mapping and apply it. Write an invite rule against groups with the Xenia role you want instead — same outcome, but it is a rule you can see and change.
• Per-message delivery outcomes are not tracked. The invite log records what was accepted for delivery, not what was delivered, bounced or marked as spam.
• No configuration API. Connecting a directory, managing invite rules and sending invites are web app only, like SSO configuration.
• No mobile support. Directory Sync is configured in the web app; there is no equivalent screen in the Xenia mobile apps.
• No webhooks. To react to accounts Directory Sync creates, poll the Get Users API.

​

Troubleshooting

​

Next Steps