Quick Start

Make sure you have:

• A WorkOS account
• 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.

Create an organization in the WorkOS Dashboard, then create a new connection to the organization’s directory. Start by creating one for development in your sandbox environment.

Select the directory provider to test for provider-specific instructions:

Integrate the Directory Sync API into your app to fetch directory resources programmatically.

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

npm install @workos-inc/node

Provide the API key and, in some cases, the client ID. Store these values as managed secrets and pass them to the SDKs either as environment variables or directly in your app’s configuration.

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

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:

• Use the events API to sync data to your application. For other sync methods, see the data syncing guide.
• Review the different types of events available. See event types.
• Learn how directory events work. See the understanding events guide.
• Optionally, stream events to Datadog. See the observability guide.