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 the 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.
Learn about syncing your user list with Azure AD SCIM.
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!
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'
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.