<!-- llms.txt: https://workos.com/llms.txt -->

# Directory group

A directory group represents an organizational unit of users in a directory provider.

## Get a Directory Group

Get the details of an existing Directory Group.

:::code-group

```bash language="curl" title="Request" tab="1"
curl "https://api.workos.com/directory_groups/directory_group_01E1JJS84MFPPQ3G655FHTKX6Z" \
  --header "Authorization: Bearer sk_example_123456789"
```

```js language="js" title="Request" tab="1"
import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const group = await workos.directorySync.getGroup(
  'directory_group_01E64QTDNS0EGJ0FMCVY9BWGZT',
);
```

```rb language="ruby" title="Request" tab="1"
require "workos"

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

WorkOS.client.directory_sync.get_group(id: "directory_group_01E1JJS84MFPPQ3G655FHTKX6Z")
```

```py language="python" title="Request" tab="1"
from workos import WorkOSClient

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

client.directory_sync.get_group(id_="directory_group_01E1JJS84MFPPQ3G655FHTKX6Z")
```

```go language="go" title="Request" tab="1"
package main

import (
	"context"

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

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

	_, err := client.DirectorySync().GetGroup(context.Background(), "directory_group_01E1JJS84MFPPQ3G655FHTKX6Z")
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

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

$workos
    ->directorySync()
    ->getGroup(id: "directory_group_01E1JJS84MFPPQ3G655FHTKX6Z");
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;

WorkOS workos = new WorkOS("sk_example_123456789");

workos.directorySync.getGroup("directory_group_01E1JJS84MFPPQ3G655FHTKX6Z");
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

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

await client.DirectorySync.GetGroupAsync("directory_group_01E1JJS84MFPPQ3G655FHTKX6Z");
```

```rust language="rust" title="Request" tab="1"
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_group("directory_group_01E1JJS84MFPPQ3G655FHTKX6Z")
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "object": "directory_group",
  "id": "directory_group_01E1JJS84MFPPQ3G655FHTKX6Z",
  "idp_id": "02grqrue4294w24",
  "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
  "organization_id": "org_01EZTR6WYX1A0DSE2CYMGXQ24Y",
  "name": "Developers",
  "raw_attributes": {},
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z"
}
```

:::

## List Directory Groups

Get a list of all of existing directory groups matching the criteria specified.

> **Note:** To fetch the groups a single user belongs to, pass the `user` query parameter
> with the directory user's ID. This is the recommended replacement for the
> `groups` field on the [Directory
> User](https://workos.com/docs/reference/directory-sync/directory-user) object, which is deprecated
> and returns an empty array by default for teams created on or after **May 1,
> 2026**. The response is bounded by a single user's memberships, which gives
> better throughput performance than the unbounded `groups` array. **Existing
> teams still depending on the legacy `groups` field should migrate to this
> access pattern.**

:::code-group

```bash language="curl" title="Request" tab="1"
curl "https://api.workos.com/directory_groups" \
  --header "Authorization: Bearer sk_example_123456789"
```

```js language="js" title="Request" tab="1"
import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const groups = await workos.directorySync.listGroups({
  directory: 'directory_01ECAZ4NV9QMV47GW873HDCX74',
});

console.log(groups.data);
```

```rb language="ruby" title="Request" tab="1"
require "workos"

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

WorkOS.client.directory_sync.list_groups
```

```py language="python" title="Request" tab="1"
from workos import WorkOSClient

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

client.directory_sync.list_groups()
```

```go language="go" title="Request" tab="1"
package main

import (
	"context"

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

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

	_, err := client.DirectorySync().ListGroups(context.Background())
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

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

$workos->directorySync()->listGroups();
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;

WorkOS workos = new WorkOS("sk_example_123456789");

workos.directorySync.listGroups();
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

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

await client.DirectorySync.ListGroupsAsync();
```

```rust language="rust" title="Request" tab="1"
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_groups()
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "object": "list",
  "data": [
    {
      "object": "directory_group",
      "id": "directory_group_01E1JJS84MFPPQ3G655FHTKX6Z",
      "idp_id": "02grqrue4294w24",
      "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
      "organization_id": "org_01EZTR6WYX1A0DSE2CYMGXQ24Y",
      "name": "Developers",
      "raw_attributes": {},
      "created_at": "2026-01-15T12:00:00.000Z",
      "updated_at": "2026-01-15T12:00:00.000Z"
    }
  ],
  "list_metadata": {
    "before": "directory_group_01HXYZ123456789ABCDEFGHIJ",
    "after": "directory_group_01HXYZ987654321KJIHGFEDCBA"
  }
}
```

:::

### directory_group

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | "directory_group" | Yes | Distinguishes the Directory Group object. |
| `id` | string | Yes | Unique identifier for the Directory Group. |
| `idp_id` | string | Yes | Unique identifier for the group, assigned by the Directory Provider. Different Directory Providers use different ID formats. |
| `directory_id` | string | Yes | The identifier of the Directory the Directory Group belongs to. |
| `organization_id` | string | Yes | The identifier for the Organization in which the Directory resides. |
| `name` | string | Yes | The name of the Directory Group. |
| `raw_attributes` | object | No | The raw attributes received from the directory provider. |
| `created_at` | string | Yes | The timestamp when the Directory Group was created. |
| `updated_at` | string | Yes | The timestamp when the Directory Group was last updated. |

### GET /directory_groups/{id}

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Unique identifier for the Directory Group. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `directory_group` | object | Distinguishes the Directory Group object. |

### GET /directory_groups

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `before` | string | No | An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with `"obj_123"`, your subsequent call can include `before="obj_123"` to fetch a new batch of objects before `"obj_123"`. |
| `after` | string | No | An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with `"obj_123"`, your subsequent call can include `after="obj_123"` to fetch a new batch of objects after `"obj_123"`. |
| `limit` | integer | No | Upper limit on the number of objects to return, between `1` and `100`. Defaults to `10`. |
| `order` | "normal" \| "desc" \| "asc" | No | Order the results by the creation time. Supported values are `"asc"` (ascending), `"desc"` (descending), and `"normal"` (descending with reversed cursor semantics where `before` fetches older records and `after` fetches newer records). Defaults to `normal`. |
| `directory` | string | No | Unique identifier of the WorkOS Directory. This value can be obtained from the WorkOS dashboard or from the WorkOS API. |
| `user` | string | No | Unique identifier of the WorkOS Directory User. This value can be obtained from the WorkOS API. |