A directory user represents an active organization user.
Developers can receive Webhooks as employees are added, updated or removed, allowing for provisioning and de-provisioning Users within an application.
Get the details of an existing Directory User.
The groups field on the directory user is deprecated. Starting May 1, 2026,
newly created teams receive groups: [] by default. Existing teams
currently depending on this field should migrate to the new access pattern for
better throughput performance – the field is unbounded by user, so users
with many group memberships produce large, slow response payloads. To fetch
the user’s group memberships, use the List Directory
Groups endpoint with a user
filter.
import { WorkOS } from '@workos-inc/node'; const workos = new WorkOS('sk_example_123456789'); const user = await workos.directorySync.getUser( 'directory_user_01E64QS50EAY48S0XJ1AA4WX4D', );
GET/directory_usersParameters Returns Get a list of all of existing Directory Users matching the criteria specified.
The groups field on each directory user is deprecated. Starting May 1, 2026,
newly created teams receive groups: [] by default. Existing teams
currently depending on this field should migrate to the new access pattern for
better throughput performance – the field is unbounded by user, so users
with many group memberships produce large, slow response payloads. To fetch a
user’s group memberships, use the List Directory
Groups endpoint with a user
filter.
import { WorkOS } from '@workos-inc/node'; const workos = new WorkOS('sk_example_123456789'); const users = await workos.directorySync.listUsers({ directory: 'directory_01ECAZ4NV9QMV47GW873HDCX74', }); console.log(users.data);
GET/directory_usersParameters Returns objectGet a list of directory users that belong to a specific directory group. The response is bounded by the size of the requested group, which keeps payloads predictable.
Starting May 1, 2026, the groups field on each returned user is empty by default for newly created teams – the caller already knows which group is being filtered. To fetch a user’s complete group memberships, use the List Directory Groups endpoint with a user filter.
import { WorkOS } from '@workos-inc/node'; const workos = new WorkOS('sk_example_123456789'); const users = await workos.directorySync.listUsers({ group: 'directory_group_01E1JG7J09H96KYP8HM9B0G5SJ', }); console.log(users.data);
directorySyncParameters objectReturns object