Set up a directory, install the SDK, and integrate Directory Sync.
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:
The WorkOS Directory Sync API exclusively uses read-only operations. We never mutate end-user directories.
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:
Learn about syncing your user list with Okta SCIM v2.0.
Learn about syncing your user list with Azure AD SCIM v2.0.
Learn about syncing your user list with Google Workspace.
Choose from dozens of Identity Providers.
You can view and copy the unique identifier for the Directory Connection on the Directory page, once it has been set up. The id takes the form directory_*
.
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.
Don't see an SDK you need? Contact us to request an SDK!
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'
Sign in to your WorkOS account to see code examples pre-filled with your API keys and resource IDs.
Get the details of an existing Directory User.
Example use case: pre-populate user attributes for new user accounts.
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', });
Use the optional limit
, before
, and after
parameters to paginate through results. See the API Reference for details.
Get the details of an existing Directory Group.
Example use case: Pre-populate team attributes for new organizations.
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', });
Use the optional limit
, before
, and after
parameters to paginate through results. See the API Reference for details.