Skip to content
Dashboard
Theme
Theme

WorkOS Directory Sync compatibility

Point the WorkOS Node SDK's Directory Sync reads and WorkOS dsync webhooks at OhAuthCat, and know where the shapes differ.

View Markdown

OhAuthCat serves the WorkOS Directory Sync reads and dsync.* webhooks, so the official WorkOS Node SDK’s Directory Sync methods work by changing only the base URL, the API key and the webhook secret. The reads are read-only: they never write directory data.

This was proven locally: the unmodified official WorkOS Node SDK 11.0.0 listed and read directories, users and groups, used both membership filters and cursor paging, and verified membership webhooks, all against a local OhAuthCat binary. No hosted WorkOS tenant or deployed compatibility service is claimed here.

Enable both the deployment compatibility gate and the environment compatibility setting. Send a native sk_… secret key as Authorization: Bearer …. Publishable keys, dashboard sessions and portal tokens are refused. When compatibility is disabled, reads return HTTP 404.

Each read is served at two paths on the API host: the unprefixed path the WorkOS SDK requests (/directories, /directories/{id}, /directory_users, /directory_users/{id}, /directory_groups, /directory_groups/{id}), the same way the SSO bridge serves /sso/*, and the prefixed path below. Both paths have the same authentication, scopes, filters, cursors and flags.

Read route Required scope
GET /compat/workos/directories directories:read
GET /compat/workos/directories/{id} directories:read
GET /compat/workos/directory_users directory_data:read
GET /compat/workos/directory_users/{id} directory_data:read
GET /compat/workos/directory_groups directory_data:read
GET /compat/workos/directory_groups/{id} directory_data:read

User lists require exactly one of directory or group; group lists require exactly one of directory or user. Missing, empty, duplicate or conflicting filters are refused in the compatibility error shape. IDs remain scoped to the key’s environment; imported legacy IDs are lookup aliases only where a mapping exists.

Pagination uses limit from 1 to 100, default 10, before or after, and order: asc|desc, default desc. Cursors are opaque and bound to the environment, route and filter. Do not reuse one for a different filter. Responses have list_metadata with before and after.

A directory user includes object, timestamps, supported state values, singular email, plural emails, groups, optional mapped custom attributes and optional role: {slug}. It omits raw_attributes and raw SCIM payloads.

  • email is the stored primary email, even when the plural emails list puts a secondary address first. It is absent when the user has no mapped email.
  • groups is WorkOS’s deprecated field and is always empty. To read a user’s groups, list directory groups with the user filter; to read a group’s members, list directory users with the group filter.

These routes do not write directory data or provision SCIM. Use the native SCIM interface for provisioning. SSO compatibility has separate authorization and token behavior. The compatibility support policy is not implemented billing or expiry enforcement.

Set a webhook endpoint’s format to workos using native webhook management; the default is native. This setting is separate from the compatibility read flags. WorkOS endpoints receive only the supported dsync.* events: directory activation/deletion, user and group creation/update/deletion, and group membership additions/removals. Other event types are filtered, not failed deliveries.

dsync.group.user_added and dsync.group.user_removed carry nested user and group objects, built from the same projections as the reads and captured when the membership changed, so a removal still describes the removed user. Native webhook events keep their flat IDs. If a membership’s captured data would exceed 256 KiB, native events are delivered as usual and the WorkOS delivery is recorded as failed instead of being sent with a partial body.

The envelope is id, event, data, created_at. Authenticate the exact raw body using WorkOS-Signature, not the native signature helper. Its timestamp t is milliseconds; each v1 is a hexadecimal HMAC-SHA256 of <t>.<body> using the full endpoint secret. Header entries are separated by , , including rotation-overlap signatures. Use WorkOS’s supported verification helper with your secret and its timestamp checks; do not parse and reserialize JSON before verification.

Local fixtures verified generated webhook bytes, including membership events, with the official WorkOS SDK helper and refused tampered bodies, altered fields and wrong secrets. That proof does not establish hosted vendor delivery. Existing retries, rotation overlap and safe destination checks remain. Queued deliveries retain their captured format after an endpoint setting changes.