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 the details of an existing directory.
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" }
| curl "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'); | |
| const directory = await workos.directorySync.getDirectory( | |
| 'directory_01ECAZ4NV9QMV47GW873HDCX74', | |
| ); |
| require "workos" | |
| WorkOS.configure do |config| | |
| config.key = "sk_example_123456789" | |
| end | |
| directory = WorkOS::DirectorySync.get_directory( | |
| id: "directory_01ECAZ4NV9QMV47GW873HDCX74" | |
| ) |
| from workos import WorkOSClient | |
| workos_client = WorkOSClient( | |
| api_key="sk_example_123456789", client_id="client_123456789" | |
| ) | |
| directory = workos_client.directory_sync.get_directory( | |
| directory_id="directory_01ECAZ4NV9QMV47GW873HDCX74" | |
| ) |
| package main | |
| import ( | |
| "context" | |
| "github.com/workos/workos-go/v3/pkg/directorysync" | |
| ) | |
| func main() { | |
| directorysync.SetAPIKey("sk_example_123456789") | |
| dir, err := directorysync.GetDirectory( | |
| context.Background(), | |
| directorysync.GetDirectoryOpts{ | |
| Directory: "directory_01ECAZ4NV9QMV47GW873HDCX74", | |
| }, | |
| ) | |
| } |
| <?php | |
| WorkOS\WorkOS::setApiKey("sk_example_123456789"); | |
| $ds = new WorkOS\DirectorySync(); | |
| $directory = $ds->getDirectory("directory_01ECAZ4NV9QMV47GW873HDCX74"); |
| import com.workos.WorkOS; | |
| import com.workos.directorysync.models.Directory; | |
| WorkOS workos = new WorkOS("sk_example_123456789"); | |
| String directoryId = "directory_01ECAZ4NV9QMV47GW873HDCX74"; | |
| Directory directory = workos.directorySync.getDirectory(directoryId); |
| WorkOS.SetApiKey("sk_example_123456789"); | |
| var directorySyncService = new DirectorySyncService(); | |
| var directoryId = "directory_01ECAZ4NV9QMV47GW873HDCX74"; | |
| var directory = await directorySyncService.GetDirectory(directoryId); |
| { | |
| "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/directoriesParameters Returns Get a list of all of your existing directories matching the criteria specified.
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" } }
| curl "https://api.workos.com/directories" \ | |
| --header "Authorization: Bearer sk_example_123456789" |
| import { WorkOS } from '@workos-inc/node'; | |
| const workos = new WorkOS('sk_example_123456789'); | |
| const directoryList = await workos.directorySync.listDirectories(); | |
| console.log(directoryList.data); |
| require "workos" | |
| WorkOS.configure do |config| | |
| config.key = "sk_example_123456789" | |
| end | |
| directories = WorkOS::DirectorySync.list_directories |
| from workos import WorkOSClient | |
| workos_client = WorkOSClient( | |
| api_key="sk_example_123456789", client_id="client_123456789" | |
| ) | |
| directories = workos_client.directory_sync.list_directories() |
| package main | |
| import ( | |
| "context" | |
| "github.com/workos/workos-go/v3/pkg/directorysync" | |
| ) | |
| func main() { | |
| directorysync.SetAPIKey("sk_example_123456789") | |
| list, err := directorysync.ListDirectories( | |
| context.Background(), | |
| directorysync.ListDirectoriesOpts{Domain: "foo-corp.com"}, | |
| ) | |
| } |
| <?php | |
| WorkOS\WorkOS::setApiKey("sk_example_123456789"); | |
| $ds = new WorkOS\DirectorySync(); | |
| [$before, $after, $directories] = $ds->listDirectories(); |
| import com.workos.WorkOS; | |
| import com.workos.directorysync.models.DirectoryList; | |
| WorkOS workos = new WorkOS("sk_example_123456789"); | |
| DirectoryList directoryList = workos.directorySync.listDirectories(); |
| WorkOS.SetApiKey("sk_example_123456789"); | |
| var directorySyncService = new DirectorySyncService(); | |
| var directoryList = await directorySyncService.ListDirectories(); |
| { | |
| "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/directoriesParameters Returns objectPermanently deletes an existing directory. It cannot be undone.
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.key = "sk_example_123456789" end WorkOS::DirectorySync.delete_directory( "directory_01ECAZ4NV9QMV47GW873HDCX74" )
from workos import WorkOSClient workos_client = WorkOSClient( api_key="sk_example_123456789", client_id="client_123456789" ) workos_client.directory_sync.delete_directory( directory_id="directory_01ECAZ4NV9QMV47GW873HDCX74" )
package main import ( "context" "github.com/workos/workos-go/v3/pkg/directorysync" ) func main() { directorysync.SetAPIKey("sk_example_123456789") err := directorysync.DeleteDirectory( context.Background(), directorysync.DeleteDirectoryOpts{ Directory: "org_01EHZNVPK3SFK441A1RGBFSHRT", }, ) }
<?php WorkOS\WorkOS::setApiKey("sk_example_123456789"); $ds = new WorkOS\DirectorySync(); $ds->deleteDirectory("directory_01ECAZ4NV9QMV47GW873HDCX74");
import com.workos.WorkOS; WorkOS workos = new WorkOS("sk_example_123456789"); String directoryId = "directory_01ECAZ4NV9QMV47GW873HDCX74"; workos.directorySync.deleteDirectory(directoryId);
WorkOS.SetApiKey("sk_example_123456789"); var directorySyncService = new DirectorySyncService(); var directoryId = "directory_01ECAZ4NV9QMV47GW873HDCX74"; await directorySyncService.DeleteDirectory(directoryId);
DELETE/directoriesParameters