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.
JavaScript
| 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.api_key = "sk_example_123456789" | |
| end | |
| WorkOS.client.directory_sync.get_directory(id: "directory_01ECAZ4NV9QMV47GW873HDCX74") |
| from workos import WorkOSClient | |
| client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789") | |
| client.directory_sync.get_directory(id_="directory_01ECAZ4NV9QMV47GW873HDCX74") |
| package main | |
| import ( | |
| "context" | |
| "github.com/workos/workos-go/v9" | |
| ) | |
| func main() { | |
| client := workos.NewClient("sk_example_123456789") | |
| _, err := client.DirectorySync().Get(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() | |
| ->getDirectory(id: "directory_01ECAZ4NV9QMV47GW873HDCX74"); |
| import com.workos.WorkOS; | |
| WorkOS workos = new WorkOS("sk_example_123456789"); | |
| workos.directorySync.getDirectory("directory_01ECAZ4NV9QMV47GW873HDCX74"); |
| using WorkOS; | |
| var client = new WorkOSClient(new WorkOSOptions { | |
| ApiKey = "sk_example_123456789", | |
| ClientId = "client_123456789", | |
| }); | |
| await client.DirectorySync.GetAsync("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() | |
| .get_directory("directory_01ECAZ4NV9QMV47GW873HDCX74") | |
| .await?; | |
| Ok(()) | |
| } |
| { | |
| "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
Get a list of all of your existing directories matching the criteria specified.
JavaScript
| 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.api_key = "sk_example_123456789" | |
| end | |
| WorkOS.client.directory_sync.list_directories |
| from workos import WorkOSClient | |
| client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789") | |
| client.directory_sync.list_directories() |
| package main | |
| import ( | |
| "context" | |
| "github.com/workos/workos-go/v9" | |
| ) | |
| func main() { | |
| client := workos.NewClient("sk_example_123456789") | |
| _, err := client.DirectorySync().List(context.Background()) | |
| if err != nil { | |
| panic(err) | |
| } | |
| } |
| <?php | |
| use WorkOS\WorkOS; | |
| $workos = new WorkOS( | |
| apiKey: "sk_example_123456789", | |
| clientId: "client_123456789", | |
| ); | |
| $workos->directorySync()->listDirectories(); |
| import com.workos.WorkOS; | |
| WorkOS workos = new WorkOS("sk_example_123456789"); | |
| workos.directorySync.listDirectories(); |
| using WorkOS; | |
| var client = new WorkOSClient(new WorkOSOptions { | |
| ApiKey = "sk_example_123456789", | |
| ClientId = "client_123456789", | |
| }); | |
| await client.DirectorySync.ListAsync(); |
| 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() | |
| .list_directories() | |
| .await?; | |
| Ok(()) | |
| } |
| { | |
| "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
Directory user Continue to the next section
Up next