Directory

A directory stores information about an organization’s employee management system.

Synchronizing with a directory enables you to receive changes to an organization’s user and group structure.

Directory providers vary in implementation details and may require different sets of fields for integration, such as API keys, subdomains, endpoints, usernames, etc. Where available, the WorkOS API will provide these fields when fetching directory records.

Get a Directory

Get the details of an existing directory.

JavaScript

 import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const directory = await workos.directorySync.getDirectory(
  'directory_01ECAZ4NV9QMV47GW873HDCX74',
);

 {
  "object": "directory",
  "id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
  "organization_id": "org_01EHZNVPK3SFK441A1RGBFSHRT",
  "external_key": "sPa12dwRQ",
  "type": "gsuite directory",
  "state": "linked",
  "name": "Foo Corp",
  "domain": "foo-corp.com",
  "metadata": {
    "users": {
      "active": 42,
      "inactive": 3
    },
    "groups": 5
  },
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z"
}

GET

`/directories/:id`

`Parameters`

`Returns`

List Directories

Get a list of all of your existing directories matching the criteria specified.

JavaScript

 import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const directoryList = await workos.directorySync.listDirectories();

console.log(directoryList.data);

 {
  "object": "list",
  "data": [
    {
      "object": "directory",
      "id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
      "organization_id": "org_01EHZNVPK3SFK441A1RGBFSHRT",
      "external_key": "sPa12dwRQ",
      "type": "gsuite directory",
      "state": "linked",
      "name": "Foo Corp",
      "domain": "foo-corp.com",
      "metadata": {
        "users": {
          "active": 42,
          "inactive": 3
        },
        "groups": 5
      },
      "created_at": "2026-01-15T12:00:00.000Z",
      "updated_at": "2026-01-15T12:00:00.000Z"
    }
  ],
  "list_metadata": {
    "before": "directory_01HXYZ123456789ABCDEFGHIJ",
    "after": "directory_01HXYZ987654321KJIHGFEDCBA"
  }
}

GET

`/directories`

`Parameters`

`Returns` `object`

Delete a Directory

Permanently deletes an existing directory. It cannot be undone.

Request

JavaScript

 curl --request DELETE \
  --url https://api.workos.com/directories/directory_01ECAZ4NV9QMV47GW873HDCX74 \
  --header "Authorization: Bearer sk_example_123456789"

 import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

await workos.directorySync.deleteDirectory(
  'directory_01ECAZ4NV9QMV47GW873HDCX74',
);

 require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.directory_sync.delete_directory(id: "directory_01ECAZ4NV9QMV47GW873HDCX74")

 from workos import WorkOSClient

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

client.directory_sync.delete_directory(id_="directory_01ECAZ4NV9QMV47GW873HDCX74")

 package main

import (
	"context"

	"github.com/workos/workos-go/v10"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.DirectorySync().Delete(context.Background(), "directory_01ECAZ4NV9QMV47GW873HDCX74")
	if err != nil {
		panic(err)
	}
}

 <?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos
    ->directorySync()
    ->deleteDirectory(id: "directory_01ECAZ4NV9QMV47GW873HDCX74");

 import com.workos.WorkOS;

WorkOS workos = new WorkOS("sk_example_123456789");

workos.directorySync.deleteDirectory("directory_01ECAZ4NV9QMV47GW873HDCX74");

 using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.DirectorySync.DeleteAsync("directory_01ECAZ4NV9QMV47GW873HDCX74");

 use workos::Client;

#[tokio::main]
async fn main() -> Result<(), workos::Error> {
    let client = Client::builder()
        .api_key("sk_example_123456789")
        .client_id("client_123456789")
        .build();

    let _result = client
        .directory_sync()
        .delete_directory("directory_01ECAZ4NV9QMV47GW873HDCX74")
        .await?;

    Ok(())
}

DELETE

`/directories/:id`

`Parameters`

Sync a Directory

Request an asynchronous sync from the directory provider. Currently supports Google Workspace directories in linked or validating state. Manual requests share a five-minute per-directory cooldown across the API, Dashboard, Admin Portal, and MCP. Acceptance means the request was queued, not that the sync has started or completed. A running sync prevents another request from being queued.

JavaScript

 import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const result = await workos.directorySync.syncDirectory(
  'directory_01ECAZ4NV9QMV47GW873HDCX74',
);

// A queued response does not mean the sync has completed.
console.log(result.status);

 {
  "status": "queued"
}

POST

`/directories/:id/sync`

`Parameters`

`Returns`

Directory user Continue to the next section

Up next

Directory

Get a Directory

/directories/:id

Parameters

id: string

Returns

directory: object

List Directories

/directories

Parameters

before?: string

after?: string

limit?: integer

order?: "normal" | "desc" | "asc"

organization_id?: string

search?: string

domain?: string

Returns object

object: "list"

data: object[]

list_metadata: object

Delete a Directory

/directories/:id

Parameters

id: string

Sync a Directory

/directories/:id/sync

Parameters

id: string

Returns

status: "queued"

`/directories/:id`

`Parameters`

`Returns`

`/directories`

`Parameters`

`Returns` `object`

`/directories/:id`

`Parameters`

`/directories/:id/sync`

`Parameters`

`Returns`