WorkOS directory deletion is not user deprovisioning

Deleting a WorkOS directory is not a substitute for removing a person’s access. In AuthKit Directory Provisioning, directory deletion leaves organization memberships active so customers can change directory providers. Deprovisioning an active member instead deactivates the membership; WorkOS documents revocation of all that user’s sessions. These are different operations with different purposes. WorkOS Directory Provisioning

For an application owner, the first question is therefore operational: are you replacing an identity provider, removing one employee, or closing a customer account? Give those actions separate runbooks. A button labeled “disconnect directory” should not carry an undocumented promise to offboard everyone.

Choose the runbook before deleting the connection

Use this decision table to define the intended outcome before making a destructive change. The final column describes recommended application checks, rather than additional WorkOS guarantees.

Intended operation	Boundary to use	Application acceptance check
Replace a customer’s directory provider	Connection migration	Reconcile the new roster and resolve discrepancies before declaring the cutover complete.
Remove one employee from one customer	Organization access	The removed customer is inaccessible; separately assess the person’s other customer relationships.
Close a customer account	Whole customer lifecycle	Disable customer access and credentials under an explicit offboarding policy; preserve required records.
Remove an invitation that was never accepted	Pending membership	The old invitation cannot admit the person later.
Respond to an account compromise	Emergency access control	Inventory every credential and active access path, including application-owned ones.

For migration, preserve a record of the intended membership set before changing the connection. For offboarding, define the access-denial checks first. The same administrator may perform both tasks, but the success criteria should make it impossible to confuse them.

AuthKit and standalone Directory Sync are different integration paths

The AuthKit documentation describes automatic user and membership changes. Active-member deprovisioning retains the user and inactive membership, whereas deprovisioning a pending member deletes the membership. Its guidance explicitly sends standalone Directory Sync users to separate documentation. Directory Provisioning currently requires contacting WorkOS to enable it. Verify that your environment uses this integration before relying on its automatic behavior. AuthKit provisioning documentation

Standalone event handling has a particularly important boundary: deleting the connection emits a single dsync.deleted event. WorkOS does not then emit dsync.user.deleted and dsync.group.deleted for every object in the removed directory. The event documentation tells applications to handle the removal of the directory association and related local state. Directory Sync event lifecycle

Consequently, an application that cleans up only in its per-user event handler needs a separate connection-deletion path. Decide whether that path initiates customer offboarding or records a controlled provider migration. Do not infer the customer’s intent merely from the event name.

Keep a mapping from the directory and organization to the local records your handler owns. During an investigation, that mapping should answer which records were affected without searching logs for email addresses. In a migration, compare the old and new assignments before declaring the cutover complete. Continue processing known offboarding requests during reconciliation. Investigate unexplained differences instead of treating a missing record in an incomplete migration snapshot as sufficient evidence to grant or remove access.

Check how inactive directory users are represented

WorkOS documents deletion of inactive directory users as the default for new environments created after October 19, 2023. Check older environments rather than assuming that default applies. A custom management flow can retain inactive users instead, and enabling that flow requires contacting support. Directory Sync event lifecycle Under the default, a returning person receives a new directory-user record; retained inactive users can be reactivated. This concerns directory records, not a universal promise about deletion of application data or AuthKit identities. Handle inactive users

Record the configured behavior in your integration runbook. Use it when designing idempotency and reconciliation: an old directory-object identifier should not be the only evidence that a returning person has already been processed. Keep identity linking an explicit decision with safeguards against merging unrelated accounts.

For customer support, distinguish “inactive in the provider,” “removed from the synchronized directory,” “inactive application membership,” and “deleted account.” Those labels describe different evidence. An incident report that says only “the user was deleted” hides the very boundary the investigation needs to establish.

Membership scope does not settle session scope

Consider a consultant with access to customers A and B. Removing access to A raises two independent questions: can the consultant still reach A, and what happens to their session while working in B?

AuthKit distinguishes domain-managed users from domain guests; for guests, directory management is scoped to the linked organization membership. However, its deprovisioning action table describes revoking all user sessions. Do not promise unaffected sessions in other organizations based only on membership scope. Directory Provisioning

WorkOS sessions use an access token and a refresh token. The access token contains organization context when applicable. Switching organizations can obtain a new token with the target organization’s role and permissions when authorized; otherwise authentication is required. WorkOS recommends short access-token duration so session changes are reflected promptly. AuthKit sessions

For your acceptance test, exercise both an already-issued token and token refresh. Also test a fresh login into each customer. Record denial of access separately from a requirement to authenticate again: interrupting a session and deleting the second customer’s membership are not the same outcome. Do not describe provider-side session revocation as measured instantaneous denial at every API unless you have demonstrated that behavior in your application.

A focused acceptance exercise

The following is a proposed test plan, not a report of executed tests. Use disposable customer organizations and identities, and capture identifiers and timestamps without retaining credentials.

1. Establish separate fixtures for an active employee, an unaccepted invitation, and a consultant with two customer memberships. Record the relevant environment settings.
2. Deprovision the active employee through the customer’s provider. Inspect membership state, test fresh login, and probe both existing-token and refresh paths.
3. Repeat for the pending invitation. Verify the resulting membership and whether the invitation can still be used.
4. Remove the consultant from one customer. Exercise both customer contexts and distinguish reauthentication from lost membership.
5. In a separate migration fixture, delete the directory connection. Confirm which event handlers ran and reconcile local state without expecting a stream of individual deletion events.
6. Reactivate or reprovision a test person. Verify their resulting role and permitted actions explicitly before accepting restoration.

Set a deadline for each access-denial check based on your customer contract, then measure actual results. Include locally issued credentials and asynchronous work in the broader SCIM deprovisioning review. A successful directory transition is only one checkpoint in demonstrating that the application now enforces the intended access.