---
title: Quick Start
description: 'Set up a directory, install the SDK, and integrate Directory Sync.'
showNextPage: true
originalPath: .tmp-workos-clone/packages/docs/content/directory-sync/quick-start.mdx
---

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

1. Create a new directory in the WorkOS Dashboard
2. Add Directory Sync to your app and fetch directory resources
3. 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](https://dashboard.workos.com/)
- A directory from a directory provider that WorkOS supports

## API object definitions

[Directory](/reference/directory-sync/directory)
: Stores info about an organization’s user management system (i.e. directory provider).

[Directory user](/reference/directory-sync/directory-user)
: Represents an organization user that is active in an organization’s directory provider.

[Directory group](/reference/directory-sync/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.

---

## (1) Create a new directory connection

The first step to connecting with a directory is creating an organization in the [WorkOS Dashboard](https://dashboard.workos.com/). You will then be able to create a new [connection](/glossary/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:

<ProviderCards.DirSyncIntegration />

> 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_*`.

---

## (2) Add 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.

<LanguageSelector>
  Install the SDK using the command below.

  <CodeBlock title="Install the WorkOS SDK" file="install-sdk">
    <CodeBlockTab language="js" file="install-sdk-npm" title="npm" />
    <CodeBlockTab language="js" file="install-sdk-yarn" title="Yarn" />
    <CodeBlockTab language="java" file="install-sdk-maven" title="Maven" />
    <CodeBlockTab language="java" file="install-sdk-gradle" title="Gradle" />
    <CodeBlockTab language="ruby" file="install-sdk-terminal" title="Terminal" />
    <CodeBlockTab language="ruby" file="install-sdk-bundler" title="Bundler" />
  </CodeBlock>
</LanguageSelector>

### 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.

```plain title="Environment variables"
WORKOS_API_KEY='sk_example_123456789'
WORKOS_CLIENT_ID='client_123456789'
```

> The code examples use your staging API keys when [signed in](https://dashboard.workos.com).

### Fetch directory resources

Get the details of an existing directory user.

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

<CodeBlock title="Get directory user" file="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.

<CodeBlock title="List directory users" file="list-directory-users" />

> Use the optional `limit`, `before`, and `after` parameters to paginate through results. See the [API Reference](/reference/pagination) for details.

#### Get directory group

Get the details of an existing directory group.

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

<CodeBlock title="Get directory group" file="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 employees to invite and create accounts for.

<CodeBlock title="List directory groups" file="list-directory-groups" />

> Use the optional `limit`, `before`, and `after` parameters to paginate through results. See the [API Reference](/reference/pagination) for details.

---

## (3) Handle 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](/events/data-syncing/events-api) to sync data to your application. To learn more about other ways to sync data, see the [data syncing guide](/events/data-syncing).
- Learn about the different types of events that you can receive. See [event types](/events).
- Understand how directory events work. See the [understanding events guide](/directory-sync/understanding-events).
- Optionally, stream events to Datadog. See the [observability guide](/events/observability/datadog).