Quick Start

Set up a directory, install the SDK, and integrate Directory Sync.

What you’ll build

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:

Create a new directory in the WorkOS Dashboard
Add Directory Sync to your app and fetch directory resources
Use events to keep your app in sync with the directory changes

Before getting started

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

A WorkOS account
A directory from a directory provider that WorkOS supports

API object definitions

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.

1Create a new directory connection

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:

Okta

Configure a directory connection to Okta.

Entra ID (Azure AD)

Configure an Entra ID directory connection.

Google Workspace

Configure a Google Workspace directory connection.

All integrations

Choose from dozens of other directory 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_*.

2Add Directory Sync to your app

Let’s integrate the Directory Sync API into your app to enable fetching directory resources programmatically.

Install the WorkOS SDK

WorkOS offers native SDKs in several popular programming languages. Choose a language below to see instructions in your application’s language.

Set secrets

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.

Environment variables

 WORKOS_API_KEY='sk_example_123456789'
WORKOS_CLIENT_ID='client_123456789'

The code examples use your staging API keys when signed in.

Fetch directory resources

Get the details of an existing directory user.

Example use case: pre-populate user attributes for new user accounts.

Get directory user

JavaScript

 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);

 require "workos"

directory_user_id = "directory_user_123"
user = WorkOS::DirectorySync.get_user(directory_user_id)

 from workos import WorkOSClient

workos_client = WorkOSClient(
    api_key="sk_example_123456789", client_id="client_123456789"
)

directory_user_id = "directory_user_123"  # The ID of the Directory User to fetch
user = workos_client.directory_sync.get_user(user_id=directory_user_id)

 package main

import (
	"context"
	"os"

	"github.com/workos/workos-go/v3/pkg/directorysync"
)

func main() {
	apiKey := os.Getenv("WORKOS_API_KEY")

	directorysync.SetAPIKey(apiKey)

	directoryUserID := "directory_user_123"
	user, err := directorysync.GetUser(context.Background(), directorysync.GetUserOpts{
		User: directoryUserID,
	})
}

 <?php

require __DIR__ . "/vendor/autoload.php";

$ds = new WorkOS\DirectorySync();

$directoryUserId = "directory_user_123";
$user = $ds->getUser($directoryUserId);

 <?php

require __DIR__ . "/vendor/autoload.php";

$ds = new WorkOS\DirectorySync();

$directoryUserId = "directory_user_123";
$user = $ds->getUser($directoryUserId);

 import com.workos.WorkOS;

WorkOS workos = new WorkOS("sk_example_123456789");

User user = workos.directorySync.getDirectoryUser("directory_user_123");

 using System;
using WorkOS;

var directorySync = new DirectorySyncService();

var directoryUserId = "directory_user_123";
var user = await 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.

List directory users

JavaScript

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

 require "workos"

# Fetch all Directory Users in a Directory
directory_id = "directory_123"
users_from_directory = WorkOS::DirectorySync.list_users(directory: directory_id)

# Fetch all Directory Users in a Directory Group
directory_group_id = "directory_group_123"
users_from_group = WorkOS::DirectorySync.list_users(group: directory_group_id)

 from workos import WorkOSClient

workos_client = WorkOSClient(
    api_key="sk_example_123456789", client_id="client_123456789"
)

# Fetch all Directory Users in a Directory
directory_id = "directory_123"
users_from_directory = workos_client.directory_sync.list_users(
    directory_id=directory_id
)

# Fetch all Directory Users in a Directory Group
directory_group_id = "directory_group_123"
users_from_group = workos_client.directory_sync.list_users(group_id=directory_group_id)

 package main

import (
	"context"
	"os"

	"github.com/workos/workos-go/v3/pkg/directorysync"
)

func main() {
	apiKey := os.Getenv("WORKOS_API_KEY")

	directorysync.SetAPIKey(apiKey)

	// Fetch all Directory Users in a Directory
	directoryID := "directory_123"
	usersFromDirectory, err := directorysync.ListUsers(context.Background(), directorysync.ListUsersOpts{
		Directory: directoryID,
	})

	// Fetch all Directory Users in a Directory
	directoryGroupID := "directory_group_123"
	usersFromGroup, err := directorysync.ListUsers(context.Background(), directorysync.ListUsersOpts{
		Group: directoryGroupID,
	})
}

 <?php

require __DIR__ . "/vendor/autoload.php";

$ds = new WorkOS\DirectorySync();

// Fetch all Directory Users in a Directory
$directoryId = "directory_123";
[$before, $after, $data] = $ds->listUsers(directory: $directoryId);

// Fetch all Directory Users in a Directory Group
$directoryGroupId = "directory_group_123";
[$before, $after, $data] = $ds->listUsers(group: $directoryGroupId);

 <?php

require __DIR__ . "/vendor/autoload.php";

$ds = new WorkOS\DirectorySync();

// Fetch all Directory Users in a Directory
$directoryId = "directory_123";
[$before, $after, $data] = $ds->listUsers(directory: $directoryId);

// Fetch all Directory Users in a Directory Group
$directoryGroupId = "directory_group_123";
[$before, $after, $data] = $ds->listUsers(group: $directoryGroupId);

 import com.workos.WorkOS;
import com.workos.directorysync.DirectorySyncApi.ListDirectoryUserOptions;
import com.workos.directorysync.models.DirectoryUserList;

WorkOS workos = new WorkOS("sk_example_123456789");

// Fetch all Directory Users in a Directory
DirectoryUserList usersFromDirectory = workos.directorySync.listDirectoryUsers(
    ListDirectoryUserOptions.builder().directory("directory_123").build());

// Fetch all Directory Users in a Directory Group
DirectoryUserList usersFromGroup = workos.directorySync.listDirectoryUsers(
    ListDirectoryUserOptions.builder().group("directory_group_123").build());

 using System;
using WorkOS;

var directorySync = new DirectorySyncService();

// Fetch all Directory Users in a Directory
var options = new ListDirectoryUsersOptions { Directory = "directory_123" };
var usersFromDirectory = await directorySync.ListDirectoryUsers(options);

// Fetch all Directory Users in a Directory Group
var options = new ListDirectoryUsersOptions { Group = "directory_group_123" };
var usersFromGroup = await directorySync.ListDirectoryUsers(options);

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

The groups property on the Directory User object is deprecated. Starting May 1, 2026, this property returns an empty array by default for newly created teams. Existing teams currently depending on this property should migrate to the new access pattern for better throughput performance – the property is unbounded by user, so users with many group memberships produce large, slow response payloads. To retrieve a user’s group memberships, use the Fetch user or group memberships patterns below.

Get directory group

Get the details of an existing directory group.

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

Get directory group

JavaScript

 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);

 require "workos"

directory_group_id = "directory_group_123"
group = WorkOS::DirectorySync.get_group(directory_group_id)

 from workos import WorkOSClient

workos_client = WorkOSClient(
    api_key="sk_example_123456789", client_id="client_123456789"
)

directory_group_id = "directory_group_123"  # The ID of the Directory Group to fetch
group = workos_client.directory_sync.get_group(directory_group_id)

 package main

import (
	"context"
	"os"

	"github.com/workos/workos-go/v3/pkg/directorysync"
)

func main() {
	apiKey := os.Getenv("WORKOS_API_KEY")

	directorysync.SetAPIKey(apiKey)

	directoryGroupID := "directory_group_123"
	group, err := directorysync.GetGroup(context.Background(), directorysync.GetGroupOpts{
		User: directoryGroupID,
	})
}

 <?php

require __DIR__ . "/vendor/autoload.php";

$ds = new WorkOS\DirectorySync();

$directoryGroupId = "directory_group_123";
$group = $ds->getGroup($directoryGroupId);

 <?php

require __DIR__ . "/vendor/autoload.php";

$ds = new WorkOS\DirectorySync();

$directoryGroupId = "directory_group_123";
$group = $ds->getGroup($directoryGroupId);

 import com.workos.WorkOS;

WorkOS workos = new WorkOS("sk_example_123456789");

String groupId = "directory_group_123";
Group group = workos.directorySync.getDirectoryGroup(groupId);

 using System;
using WorkOS;

var directorySync = new DirectorySyncService();

var directoryGroupId = "directory_group_123";
var user = await 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.

List directory groups

JavaScript

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

 require "workos"

# Fetch all Directory Groups in a Directory
directory_id = "directory_123"
groups_from_directory = WorkOS::DirectorySync.list_groups(directory: directory_id)

# Fetch all Directory Groups for a Directory User
directory_user_id = "directory_user_123"
groups_from_user = WorkOS::DirectorySync.list_groups(user: directory_user_id)

 from workos import WorkOSClient

workos_client = WorkOSClient(
    api_key="sk_example_123456789", client_id="client_123456789"
)

# Fetch all Directory Groups in a Directory
directory_id = "directory_123"
groups_from_directory = workos_client.directory_sync.list_groups(
    directory_id=directory_id
)

# Fetch all Directory Groups for a Directory User
directory_user_id = "directory_user_123"
groups_from_user = workos_client.directory_sync.list_groups(user_id=directory_user_id)

 package main

import (
	"context"
	"os"

	"github.com/workos/workos-go/v3/pkg/directorysync"
)

func main() {
	apiKey := os.Getenv("WORKOS_API_KEY")

	directorysync.SetAPIKey(apiKey)

	// Fetch all Directory Groups in a Directory
	directoryID := "directory_123"
	groupsFromDirectory, err := directorysync.ListUsers(context.Background(), directorysync.ListGroupsOpts{
		Directory: directoryID,
	})

	// Fetch all Directory Groups for a Directory User
	directoryUserID := "directory_user_123"
	groupsFromUser, err := directorysync.ListGroups(context.Background(), directorysync.ListGroupsOpts{
		User: directoryUserID,
	})
}

 <?php

require __DIR__ . "/vendor/autoload.php";

$ds = new WorkOS\DirectorySync();

// Fetch all Directory Groups in a Directory
$directoryId = "directory_123";
[$before, $after, $data] = $ds->listGroups(directory: $directoryId);

// Fetch all Directory Groups for a Directory User
$directoryUserId = "directory_user_123";
[$before, $after, $data] = $ds->listGroups(user: $directoryUserId);

 <?php

require __DIR__ . "/vendor/autoload.php";

$ds = new WorkOS\DirectorySync();

// Fetch all Directory Groups in a Directory
$directoryId = "directory_123";
$groupsFromDirectory = $ds->listGroups(directory: $directoryId);

// Fetch all Directory Groups for a Directory User
$directoryUserId = "directory_user_123";
$groupsFromUser = $ds->listGroups(user: $directoryUserId);

 import com.workos.WorkOS;
import com.workos.directorysync.DirectorySyncApi.ListDirectoryGroupOptions;
import com.workos.directorysync.models.DirectoryGroupList;

WorkOS workos = new WorkOS("sk_example_123456789");

// Fetch all Directory Groups in a Directory
DirectoryGroupList groupsFromDirectory = workos.directorySync.listDirectoryGroups(
    ListDirectoryGroupOptions.builder().directory("directory_123").build());

// Fetch all Directory Groups for a Directory User
DirectoryGroupList groupsFromUser = workos.directorySync.listDirectoryGroups(
    ListDirectoryGroupOptions.builder().user("directory_user_123").build());

 using System;
using WorkOS;

var directorySync = new DirectorySyncService();

// Fetch all Directory Groups in a Directory
var options = new ListGroupsOptions { Directory = "directory_123" };
var groupsFromDirectory = await directorySync.ListGroups(options);

// Fetch all Directory Groups for a Directory User
var options = new ListGroupsOptions { User = "directory_user_123" };
var groupsFromUser = await directorySync.ListGroups(options);

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

Fetch user or group memberships

To fetch the relationship between a specific user and group, scope the list endpoints with a filter parameter. This pattern keeps response payloads bounded by the size of a single user or group, and is the recommended replacement for the deprecated groups field on the directory user object.

To list users that belong to a specific group, pass the group parameter to List directory users:

List directory users by group

JavaScript

 const { WorkOS } = require('@workos-inc/node');

const workos = new WorkOS(process.env.WORKOS_API_KEY);

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

 require "workos"

# Fetch all Directory Users in a Directory Group
directory_group_id = "directory_group_123"
users_from_group = WorkOS::DirectorySync.list_users(group: directory_group_id)

 from workos import WorkOSClient

workos_client = WorkOSClient(
    api_key="sk_example_123456789", client_id="client_123456789"
)

# Fetch all Directory Users in a Directory Group
directory_group_id = "directory_group_123"
users_from_group = workos_client.directory_sync.list_users(group_id=directory_group_id)

 package main

import (
	"context"
	"os"

	"github.com/workos/workos-go/v3/pkg/directorysync"
)

func main() {
	apiKey := os.Getenv("WORKOS_API_KEY")

	directorysync.SetAPIKey(apiKey)

	// Fetch all Directory Users in a Directory Group
	directoryGroupID := "directory_group_123"
	usersFromGroup, err := directorysync.ListUsers(context.Background(), directorysync.ListUsersOpts{
		Group: directoryGroupID,
	})
}

 <?php

require __DIR__ . "/vendor/autoload.php";

$ds = new WorkOS\DirectorySync();

// Fetch all Directory Users in a Directory Group
$directoryGroupId = "directory_group_123";
[$before, $after, $data] = $ds->listUsers(group: $directoryGroupId);

 <?php

require __DIR__ . "/vendor/autoload.php";

$ds = new WorkOS\DirectorySync();

// Fetch all Directory Users in a Directory Group
$directoryGroupId = "directory_group_123";
[$before, $after, $data] = $ds->listUsers(group: $directoryGroupId);

 import com.workos.WorkOS;
import com.workos.directorysync.DirectorySyncApi.ListDirectoryUserOptions;
import com.workos.directorysync.models.DirectoryUserList;

WorkOS workos = new WorkOS("sk_example_123456789");

// Fetch all Directory Users in a Directory Group
DirectoryUserList usersFromGroup = workos.directorySync.listDirectoryUsers(
    ListDirectoryUserOptions.builder().group("directory_group_123").build());

 using System;
using WorkOS;

var directorySync = new DirectorySyncService();

// Fetch all Directory Users in a Directory Group
var options = new ListDirectoryUsersOptions { Group = "directory_group_123" };
var usersFromGroup = await directorySync.ListDirectoryUsers(options);

To list groups a specific user belongs to, pass the user parameter to List directory groups:

List directory groups by user

JavaScript

 const { WorkOS } = require('@workos-inc/node');

const workos = new WorkOS(process.env.WORKOS_API_KEY);

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

 require "workos"

# Fetch all Directory Groups for a Directory User
directory_user_id = "directory_user_123"
groups_from_user = WorkOS::DirectorySync.list_groups(user: directory_user_id)

 from workos import WorkOSClient

workos_client = WorkOSClient(
    api_key="sk_example_123456789", client_id="client_123456789"
)

# Fetch all Directory Groups for a Directory User
directory_user_id = "directory_user_123"
groups_from_user = workos_client.directory_sync.list_groups(user_id=directory_user_id)

 package main

import (
	"context"
	"os"

	"github.com/workos/workos-go/v3/pkg/directorysync"
)

func main() {
	apiKey := os.Getenv("WORKOS_API_KEY")

	directorysync.SetAPIKey(apiKey)

	// Fetch all Directory Groups for a Directory User
	directoryUserID := "directory_user_123"
	groupsFromUser, err := directorysync.ListGroups(context.Background(), directorysync.ListGroupsOpts{
		User: directoryUserID,
	})
}

 <?php

require __DIR__ . "/vendor/autoload.php";

$ds = new WorkOS\DirectorySync();

// Fetch all Directory Groups for a Directory User
$directoryUserId = "directory_user_123";
[$before, $after, $data] = $ds->listGroups(user: $directoryUserId);

 <?php

require __DIR__ . "/vendor/autoload.php";

$ds = new WorkOS\DirectorySync();

// Fetch all Directory Groups for a Directory User
$directoryUserId = "directory_user_123";
$groupsFromUser = $ds->listGroups(user: $directoryUserId);

 import com.workos.WorkOS;
import com.workos.directorysync.DirectorySyncApi.ListDirectoryGroupOptions;
import com.workos.directorysync.models.DirectoryGroupList;

WorkOS workos = new WorkOS("sk_example_123456789");

// Fetch all Directory Groups for a Directory User
DirectoryGroupList groupsFromUser = workos.directorySync.listDirectoryGroups(
    ListDirectoryGroupOptions.builder().user("directory_user_123").build());

 using System;
using WorkOS;

var directorySync = new DirectorySyncService();

// Fetch all Directory Groups for a Directory User
var options = new ListGroupsOptions { User = "directory_user_123" };
var groupsFromUser = await directorySync.ListGroups(options);

3Handle directory events

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.

Example Apps View sample Directory Sync apps for each SDK

Up next