WorkOS Docs Homepage
Directory Sync

Directory Sync

Build frictionless onboarding for entire organizations with real‑time provisioning and deprovisioning of users.

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 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 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:

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.

Environment Variables
cURL

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 User

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.

List Directory Users

Use the optional limit, before, and after parameters to paginate through results. See the API Reference for details.

Get Directory Group

Get the details of an existing Directory Group.

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

Get Directory Group

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.

List Directory Groups

Use the optional limit, before, and after parameters to paginate through results. See the API Reference for details.