Quick Start

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 events to keep your app in sync with the 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 the organization’s directory. Let’s start by creating one for development in your sandbox environment

Get provider-specific instructions by selecting the directory provider you want to test:

Let’s integrate the Directory Sync API into 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.

npm install @workos-inc/node

To make calls to WorkOS, provide the API key and, in some cases, the client ID. Store these values as managed secrets, such as WORKOS_API_KEY and WORKOS_CLIENT_ID, and pass them to the SDKs either as environment variables or directly in your app’s configuration based on your preferences.

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';
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 usersFromDirectory = await workos.directorySync.listUsers({
  directory: 'directory_123',
});

// Fetch all Directory Users in a Directory Group
const usersByGroup = await workos.directorySync.listUsers({
  group: 'directory_group_123',
});

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';
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 employees 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 groupsFromDirectory = await workos.directorySync.listGroups({
  // The ID of the Directory to fetch Directory Groups for
  directory: 'directory_123',
});

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

Actions performed in a WorkOS environment are represented by events. These can occur as a result of user-related actions, manually via the WorkOS dashboard, or via API calls. To keep your app in sync with the latest directory data, follow the corresponding guides:

• We recommend using our events API to sync data to your application. To learn more about other ways to sync data, see the data syncing guide.
• Learn about the different types of events that you can receive. See event types.
• Understand how directory events work. See the understanding events guide.
• Optionally, stream events to Datadog. See the observability guide.