# WorkOS Directory Sync compatibility

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.

## Authenticate within one environment

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](/migrate/compat-workos/) 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](/directory-sync/scim-concepts/) for provisioning. [SSO compatibility](/migrate/compat-workos/) has separate authorization and token behavior. The [compatibility support policy](/migrate/compat-workos/#support-policy) is not implemented billing or expiry enforcement.

## Select WorkOS-format webhooks

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.
