Directory provisioning (SCIM 2.0)

SCIM lets your identity provider (Okta, Microsoft Entra ID, …) manage accounts in your Zynth Auth (Perihelium's authentication layer) organization automatically: when someone joins, moves teams, or leaves in your directory, the change flows here without anyone touching Zynth Auth by hand.

The point of SCIM is offboarding. When your IdP deactivates a user, Zynth Auth suspends their membership and ends every one of their active sessions immediately — on every device — not at the next token refresh.

Switched off on the managed service. SCIM provisioning is built and switched off on Zynth's managed service, together with enterprise SSO (one flag governs both); ask us to enable it for your organization. Self-hosting: it ships off; set SSO_FEDERATION_ENABLED=true. Minting a SCIM token also needs a plan that includes it.

Setting it up

On Settings → Organization → Enterprise SSO → Provisioning (SCIM) (requires tenant:manage):

1. Turn on Enable SCIM provisioning and set a default role for newly provisioned members.
2. Generate a token. The bearer token is shown once — copy it immediately; it can't be retrieved later (only a hash is stored). Copy the SCIM base URL too.
3. In your IdP's SCIM/provisioning app, paste the base URL and the token, and assign users/groups.

Rotating the token replaces it (the old one stops working at once); revoking it stops provisioning entirely. Existing accounts are unaffected by a rotate or revoke.

What SCIM manages

• Users — create, update (PUT/PATCH), and deactivate. A provisioned user is a workforce member of your organization; the id Zynth Auth returns is stable, and your IdP's externalId is stored for round-tripping. Re-sending a create for the same externalId is safe — it returns the existing account, never a duplicate.
• Groups — Zynth Auth's groups are your organization's roles. Adding a user to a group via SCIM sets their role; removing them returns them to the default role.
• Discovery — /ServiceProviderConfig, /ResourceTypes, /Schemas are served so IdPs can auto-configure. Filtering is supported for userName eq "…" and externalId eq "…".

Deactivation and deletion

Both active: false (via PATCH/PUT, or in a create for a person your organization already has) and a SCIM DELETE deprovision the user: their membership is suspended, every active session is revoked right away, and the apps they connected through Zynth Auth's OpenID Provider stop working — those grant sessions are ended and each relying party receives a back-channel logout, rather than the app staying signed in until its next token refresh. Deprovisioning also ends the delegations the person was party to, in the same transaction as the suspension: what they had lent to colleagues (and everything those colleagues passed on) and what had been lent to them. A colleague's access that rested on the deprovisioned person's authority stops immediately, not when a cached permission set next expires. The scim.user_deprovisioned event carries how many were ended (delegations_ended).

Reactivating (active: true) restores access to the account but does not bring back delegations that were ended; grant them again if they are wanted. Zynth Auth will refuse to deprovision your organization's sole owner — reassign ownership first — so an IdP misconfiguration can't lock the organization out.

Deprovisioning leaves the stored externalId on the suspended membership. When the person exercises their right to erasure, Zynth Auth removes the externalId from their membership in every organization, including memberships that were already deprovisioned, and the directory identifier no longer appears in any organization's record of them.

Which identities your directory may manage

Zynth Auth accounts are one person across every organization: the same address can be a member of yours and of someone else's. So your directory manages the people your organization already governs, and cannot reach anyone else's account — the same rule enterprise SSO applies when it links a sign-in to an existing account.

Two refusals follow from it, and both are SCIM 409 errors that change nothing:

What your IdP tried	What you get back	What to do
Create a user whose email address already belongs to someone who is not a member of your organization	409, scimType: uniqueness, detail email already exists	Invite the person into your organization first (they accept), then re-run provisioning — the create then links their existing membership instead of claiming the account.
Change userName (the sign-in address) to an address in a domain your organization has not verified	409, scimType: mutability, with a detail naming the fix	Verify the new domain first (POST /api/v1/members/domains + the TXT record, see Team members), then retry — or deprovision the person and provision them under the new address.

The first refusal is deliberately identical to the one you get when an address is simply taken: it never tells you whether the address belongs to another organization. Renames within a domain you have verified (a name change, a UPN change) work normally, in PUT and in both PATCH forms.

An address your directory itself provisioned is treated as verified — your directory is authoritative for the addresses it creates. An address it merely claims is not: linking an existing member does not mark their email verified on their behalf.

Group sync and separation of duties

Group membership changes create and retire real role assignments through the same authorization path the console uses. If your tenant defines separation-of-duties rules, a group change that would hand one person a mutually-exclusive combination is refused with a SCIM 409 and changes nothing — resolve it in the IdP, or route the grant through an access request with a deliberate override.