Directory Sync

Organizations use directories to easily manage users and enforce their access to organization resources. Directories enable IT admins to activate and deactivate accounts, create groups that inform access rules, accelerate adoption of new tools, and more.

Get seamless user lifecycle management for both you and your customers by keeping your app in sync with the user directory – Directory Sync enables automatic updates for your app whenever there are changes to users, groups, or access rules in the connected directory.

In this guide, we’ll take you from learning about Directory Sync and POC-ing all the way through to building production-ready features fully integrated with the WorkOS Directory Sync API.

This guide will show you how to:

1. Create a new Directory in the WorkOS Dashboard
2. Add Directory Sync to your app and fetch Directory resources
3. Use webhooks to receive real-time events relating to Directory changes

To get the most out of this guide, you’ll need:

• A WorkOS account
• A directory from a Directory Provider that WorkOS supports

Directory

Stores info about an Organization’s user management system (i.e. Directory Provider).

Directory User

Represents an Organization user that is active in an Organization’s Directory Provider.

Directory Group

A collection of Organization users within a Directory, e.g. IT, database admins, HR.

The first step to connecting with a directory is creating an Organization in the WorkOS Dashboard. You will then be able to create a new Connection to your organization’s directory. Let’s start by creating one for development in your Sandbox Project

Get provider-specific instructions by selecting the Identity Provider you’re planning to use:

Okta

Learn about syncing your user list with Okta SCIM v2.0.

Azure AD

Learn about syncing your user list with Azure AD SCIM v2.0.

Google Workspace

Learn about syncing your user list with Google Workspace.

View all integrations

Choose from dozens of Identity Providers.

Let’s add Directory Sync to your app to enable fetching Directory resources programmatically.

WorkOS offers native SDKs in several popular programming languages. Choose a language below to see instructions in your application’s language.

As a best practice, your WorkOS API key should be kept secret and set as an environment variable on process start. The SDK is able to read the key automatically if you store it in an environment variable named WORKOS_API_KEY; otherwise, you will need to set it manually. The Client ID should also be set dynamically based on the release environment.

WORKOS_API_KEY='sk_example_123456789'
WORKOS_CLIENT_ID='client_123456789'

Get the details of an existing Directory User.

Example use case: pre-populate user attributes for new user accounts.

const { WorkOS } = require('@workos-inc/node');

const workos = new WorkOS(process.env.WORKOS_API_KEY);

const directoryUserID = 'directory_user_123'; // The ID of the Directory User to fetch
const user = await workos.directorySync.getUser(directoryUserID);

List Directory Users

Get Directory Users for a given Directory or Directory Group.

Example use case: Build an onboarding experience that allows an admin to select who to invite and create accounts for.

const { WorkOS } = require('@workos-inc/node');

const workos = new WorkOS(process.env.WORKOS_API_KEY);

// Fetch all Directory Users in a Directory
const directoryID = 'directory_123'; // The ID of the Directory to fetch Directory Users for
const usersFromDirectory = await workos.directorySync.listUsers({
  directory: directoryID,
});

// Fetch all Directory Users in a Directory Group
const directoryGroupID = 'directory_group_123'; // The ID of the Directory Group to fetch Directory Users for
const usersbyGroup = await workos.directorySync.listUsers({
  group: directoryGroupID,
});

Get Directory Group

Get the details of an existing Directory Group.

Example use case: Pre-populate team attributes for new organizations.

const { WorkOS } = require('@workos-inc/node');

const workos = new WorkOS(process.env.WORKOS_API_KEY);

const directoryGroupID = 'directory_group_123'; // The ID of the Directory Group to fetch
const group = await workos.directorySync.getGroup(directoryGroupID);

List Directory Groups

Get Directory Groups for a given Directory or Directory User.

Example use case: Build an onboarding experience that allows an admin to select which groups of employes to invite and create accounts for.

const { WorkOS } = require('@workos-inc/node');

const workos = new WorkOS(process.env.WORKOS_API_KEY);

// Fetch all Directory Groups in a Directory
const directoryID = 'directory_123'; // The ID of the Directory to fetch Directory Groups for
const groupsFromDirectory = await workos.directorySync.listGroups({
  directory: directoryID,
});

// Fetch all Directory Groups for a Directory User
const directoryUserID = 'directory_user_123'; // The ID of the Directory User to fetch Directory Groups for
const groupsbyUser = await workos.directorySync.listGroups({
  user: directoryUserID,
});