Skip to main content
The Directory Sync API allows you to retrieve and manage directories, users, and groups synced from identity providers like Okta, Azure AD, and Google Workspace.

Initialize

import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

Methods

listDirectories

Retrieve a list of directories.
const directories = await workos.directorySync.listDirectories({
  organizationId: 'org_123',
  limit: 10,
});

for await (const directory of directories) {
  console.log(directory.id, directory.name, directory.type);
}
options
ListDirectoriesOptions
Options for filtering and paginating directories.
directories
AutoPaginatable<Directory>
An auto-paginatable list of directories.

getDirectory

Retrieve a directory by ID.
const directory = await workos.directorySync.getDirectory('directory_123');

console.log(directory.name, directory.type);
id
string
required
The unique identifier of the directory.
directory
Directory
The directory object.

deleteDirectory

Delete a directory.
await workos.directorySync.deleteDirectory('directory_123');
id
string
required
The unique identifier of the directory to delete.

listGroups

Retrieve groups from a directory.
const groups = await workos.directorySync.listGroups({
  directory: 'directory_123',
  limit: 20,
});

for await (const group of groups) {
  console.log(group.id, group.name);
}
options
ListDirectoryGroupsOptions
required
groups
AutoPaginatable<DirectoryGroup>
An auto-paginatable list of directory groups.

getGroup

Retrieve a group by ID.
const group = await workos.directorySync.getGroup('directory_group_123');

console.log(group.name);
group
string
required
The unique identifier of the group.
group
DirectoryGroup
The directory group object.

listUsers

Retrieve users from a directory.
const users = await workos.directorySync.listUsers({
  directory: 'directory_123',
  limit: 20,
});

for await (const user of users) {
  console.log(user.id, user.email, user.firstName, user.lastName);
}
options
ListDirectoryUsersOptions
required
users
AutoPaginatable<DirectoryUserWithGroups>
An auto-paginatable list of directory users with their groups.

getUser

Retrieve a user by ID.
const user = await workos.directorySync.getUser('directory_user_123');

console.log(user.email, user.groups);
user
string
required
The unique identifier of the user.
user
DirectoryUserWithGroups
The directory user object with groups.

Custom Attributes

The listUsers and getUser methods support TypeScript generics for custom attributes:
interface CustomAttributes {
  department: string;
  employeeId: string;
}

const users = await workos.directorySync.listUsers<CustomAttributes>({
  directory: 'directory_123',
});

for await (const user of users) {
  console.log(user.customAttributes.department);
  console.log(user.customAttributes.employeeId);
}

Supported Directory Types

The following identity providers are supported:
  • azure scim v2.0
  • okta scim v2.0
  • onelogin scim v2.0
  • jump cloud scim v2.0
  • gsuite directory
  • generic scim v2.0
  • rippling scim v2.0
  • bamboohr
  • breathe hr
  • cezanne hr
  • fourth hr
  • hibob
  • people hr
  • personio
  • workday
  • And more…

Build docs developers (and LLMs) love