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 for filtering and paginating directories. Filter directories by organization ID.
Maximum number of records to return.
directories
AutoPaginatable<Directory>
An auto-paginatable list of directories. Show Directory properties
Unique identifier for the directory.
Domain associated with the directory.
External key from the identity provider.
ID of the linked organization.
Current state: active, inactive, deleting, invalid_credentials, or validating.
Identity provider type (e.g., okta scim v2.0, azure scim v2.0).
ISO-8601 timestamp of creation.
ISO-8601 timestamp of last update.
getDirectory
Retrieve a directory by ID.
const directory = await workos . directorySync . getDirectory ( 'directory_123' );
console . log ( directory . name , directory . type );
The unique identifier of the directory.
deleteDirectory
Delete a directory.
await workos . directorySync . deleteDirectory ( 'directory_123' );
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
Maximum number of records to return.
groups
AutoPaginatable<DirectoryGroup>
An auto-paginatable list of directory groups. Show DirectoryGroup properties
Unique identifier for the group.
Group ID from the identity provider.
ID of the parent directory.
ID of the linked organization.
Raw attributes from the identity provider.
ISO-8601 timestamp of creation.
ISO-8601 timestamp of last update.
getGroup
Retrieve a group by ID.
const group = await workos . directorySync . getGroup ( 'directory_group_123' );
console . log ( group . name );
The unique identifier of the group.
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
Filter users by group ID.
Maximum number of records to return.
users
AutoPaginatable<DirectoryUserWithGroups>
An auto-paginatable list of directory users with their groups. Show DirectoryUserWithGroups properties
Unique identifier for the user.
ID of the parent directory.
ID of the linked organization.
User ID from the identity provider.
User’s state in the directory.
Custom attributes from the identity provider.
Raw attributes from the identity provider.
Groups the user belongs to.
ISO-8601 timestamp of creation.
ISO-8601 timestamp of last update.
getUser
Retrieve a user by ID.
const user = await workos . directorySync . getUser ( 'directory_user_123' );
console . log ( user . email , user . groups );
The unique identifier of the user.
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…