Directory Sync allows you to connect with directory providers to inform your application of any changes in their users, groups, or access rules.
Using Directory Sync, one integration grants your application the ability to support multiple directory providers. Get real-time updates of any changes to the organization’s access rules, groups, and users by integrating webhooks into your application.
To automatically respond to changes in the connected directories and their users and groups, use the Directory Sync events.
A directory stores information about an organization’s employee management system.
Synchronizing with a directory enables you to receive changes to an organization’s user and group structure.
Directory providers vary in implementation details and may require different sets of fields for integration, such as API keys, subdomains, endpoints, usernames, etc. Where available, the WorkOS API will provide these fields when fetching directory records.
const directory = { object: 'directory', id: 'directory_01ECAZ4NV9QMV47GW873HDCX74', domain: 'foo-corp.com', name: 'Foo Corp', organizationId: 'org_01EHZNVPK3SFK441A1RGBFSHRT', state: 'inactive', type: 'gsuite directory', createdAt: '2021-06-25T19:07:33.155Z', updatedAt: '2021-06-25T19:07:33.155Z', };
interface DirectoryGet the details of an existing directory.
import { WorkOS } from '@workos-inc/node'; const workos = new WorkOS('sk_example_123456789'); const directory = await workos.directorySync.getDirectory( 'directory_01ECAZ4NV9QMV47GW873HDCX74', );
Get a list of all of your existing directories matching the criteria specified.
import { WorkOS } from '@workos-inc/node'; const workos = new WorkOS('sk_example_123456789'); const directoryList = await workos.directorySync.listDirectories(); console.log(directoryList.data);
directorySyncParameters objectReturns objectPermanently deletes an existing directory. It cannot be undone.
import { WorkOS } from '@workos-inc/node'; const workos = new WorkOS('sk_example_123456789'); await workos.directorySync.deleteDirectory( 'directory_01ECAZ4NV9QMV47GW873HDCX74', );
directorySyncParameters 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.
const user = { id: 'directory_user_01E1JG7J09H96KYP8HM9B0G5SJ', idpId: '2836', directoryId: 'directory_01ECAZ4NV9QMV47GW873HDCX74', organizationId: 'org_01EZTR6WYX1A0DSE2CYMGXQ24Y', firstName: 'Marcelina', lastName: 'Davis', emails: [ { primary: true, type: 'work', value: 'marcelina@example.com', }, ], username: 'marcelina@example.com', groups: [ { id: 'directory_group_01E64QTDNS0EGJ0FMCVY9BWGZT', name: 'Engineering', createdAt: '2021-06-25T19:07:33.155Z', updatedAt: '2021-06-25T19:07:33.155Z', rawAttributes: {}, }, ], state: 'active', createdAt: '2021-06-25T19:07:33.155Z', updatedAt: '2021-06-25T19:07:33.155Z', customAttributes: { department: 'Engineering', jobTitle: 'Software Engineer', }, rawAttributes: {}, role: { slug: 'member' }, };
interface DirectoryUserGet the details of an existing Directory User.
import { WorkOS } from '@workos-inc/node'; const workos = new WorkOS('sk_example_123456789'); const user = await workos.directorySync.getUser( 'directory_user_01E64QS50EAY48S0XJ1AA4WX4D', );
Get a list of all of existing Directory Users matching the criteria specified.
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);
directorySyncParameters objectReturns objectA directory group represents an organizational unit of users in a directory provider.
const group = { id: 'directory_group_01E64QTDNS0EGJ0FMCVY9BWGZT', idpId: '02grqrue4294w24', directoryId: 'directory_01ECAZ4NV9QMV47GW873HDCX74', organizationId: 'org_01EZTR6WYX1A0DSE2CYMGXQ24Y', name: 'Developers', createdAt: '2021-06-25T19:07:33.155Z', updatedAt: '2021-06-25T19:07:33.155Z', rawAttributes: {}, };
interface DirectoryGroupGet the details of an existing Directory Group.
import { WorkOS } from '@workos-inc/node'; const workos = new WorkOS('sk_example_123456789'); const group = await workos.directorySync.getGroup( 'directory_group_01E64QTDNS0EGJ0FMCVY9BWGZT', );
Get a list of all of existing directory groups matching the criteria specified.
import { WorkOS } from '@workos-inc/node'; const workos = new WorkOS('sk_example_123456789'); const groups = await workos.directorySync.listGroups({ directory: 'directory_01ECAZ4NV9QMV47GW873HDCX74', }); console.log(groups.data);
directorySyncParameters objectReturns object