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:

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

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';
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 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 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',
});