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

# Group

A Group is a collection of [Organization Memberships](https://workos.com/docs/reference/authkit/organization-membership) within an [Organization](https://workos.com/docs/reference/organization). Use Groups to organize users into organizational units.

To list the groups that a specific Organization Membership belongs to, use [List Groups](https://workos.com/docs/reference/authkit/organization-membership/list-groups).

:::code-group{title="Example Group"}

```json language="curl"
{
  "object": "group",
  "id": "group_01HXYZ123456789ABCDEFGHIJ",
  "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
  "name": "Engineering",
  "description": "The engineering team",
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z"
}
```

:::

## Add a member to a Group

Add an organization membership to a group.

:::code-group

```bash language="curl" title="Request" tab="1"
curl --request POST \
  --url "https://api.workos.com/organizations/org_01EHWNCE74X7JSDV0X3SZ3KJNY/groups/group_01HXYZ123456789ABCDEFGHIJ/organization-memberships" \
  --header "Authorization: Bearer sk_example_123456789" \
  --header "Content-Type: application/json" \
  -d @- <<'BODY'
    {
        "organization_membership_id": "om_01HXYZ123456789ABCDEFGHIJ"
    }
BODY
```

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

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

WorkOS.client.groups.create_group_organization_membership(
  organization_id: "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
  group_id: "group_01HXYZ123456789ABCDEFGHIJ",
  organization_membership_id: "om_01HXYZ123456789ABCDEFGHIJ"
)
```

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

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

client.groups.create_group_organization_membership(
    organization_id="org_01EHWNCE74X7JSDV0X3SZ3KJNY",
    group_id="group_01HXYZ123456789ABCDEFGHIJ",
    organization_membership_id="om_01HXYZ123456789ABCDEFGHIJ",
)
```

```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.Groups().CreateOrganizationMembership(context.Background(), "org_01EHWNCE74X7JSDV0X3SZ3KJNY", "group_01HXYZ123456789ABCDEFGHIJ", &workos.GroupsCreateOrganizationMembershipParams{
		OrganizationMembershipID: "om_01HXYZ123456789ABCDEFGHIJ",
	})
	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
    ->groups()
    ->createGroupOrganizationMembership(
        organizationId: "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
        groupId: "group_01HXYZ123456789ABCDEFGHIJ",
        organizationMembershipId: "om_01HXYZ123456789ABCDEFGHIJ",
    );
```

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

WorkOS workos = new WorkOS("sk_example_123456789");

CreateGroupOrganizationMembershipOptions options =
    CreateGroupOrganizationMembershipOptions.builder()
        .organizationMembershipId("om_01HXYZ123456789ABCDEFGHIJ")
        .build();

workos.groups.createGroupOrganizationMembership(
    "org_01EHWNCE74X7JSDV0X3SZ3KJNY", "group_01HXYZ123456789ABCDEFGHIJ", options);
```

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

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

await client.Groups.CreateOrganizationMembershipAsync("org_01EHWNCE74X7JSDV0X3SZ3KJNY",
                                                      "group_01HXYZ123456789ABCDEFGHIJ",
                                                      new GroupsCreateOrganizationMembershipOptions {
                                                          OrganizationMembershipId = "om_01HXYZ123456789ABCDEFGHIJ",
                                                      });
```

```rust language="rust" title="Request" tab="1"
use workos::Client;
use workos::groups::CreateGroupOrganizationMembershipParams;

#[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
        .groups()
        .create_group_organization_membership(
            "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
            "group_01HXYZ123456789ABCDEFGHIJ",
            CreateGroupOrganizationMembershipParams {
                organization_membership_id: "om_01HXYZ123456789ABCDEFGHIJ".into(),
                ..Default::default()
            }
        )
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "object": "group",
  "id": "group_01HXYZ123456789ABCDEFGHIJ",
  "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
  "name": "Engineering",
  "description": "The engineering team",
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z"
}
```

:::

## Create a group

Create a new group within an organization.

:::code-group

```bash language="curl" title="Request" tab="1"
curl --request POST \
  --url "https://api.workos.com/organizations/org_01EHWNCE74X7JSDV0X3SZ3KJNY/groups" \
  --header "Authorization: Bearer sk_example_123456789" \
  --header "Content-Type: application/json" \
  -d @- <<'BODY'
    {
        "name": "Engineering",
        "description": "The engineering team"
    }
BODY
```

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

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

WorkOS.client.groups.create_organization_group(
  organization_id: "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
  name: "Engineering"
)
```

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

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

client.groups.create_organization_group(
    organization_id="org_01EHWNCE74X7JSDV0X3SZ3KJNY", name="Engineering"
)
```

```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.Groups().CreateOrganizationGroup(context.Background(), "org_01EHWNCE74X7JSDV0X3SZ3KJNY", &workos.GroupsCreateOrganizationGroupParams{
		Name: "Engineering",
	})
	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
    ->groups()
    ->createOrganizationGroup(
        organizationId: "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
        name: "Engineering",
    );
```

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

WorkOS workos = new WorkOS("sk_example_123456789");

CreateOrganizationGroupOptions options =
    CreateOrganizationGroupOptions.builder().name("Engineering").build();

workos.groups.createOrganizationGroup("org_01EHWNCE74X7JSDV0X3SZ3KJNY", options);
```

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

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

await client.Groups.CreateOrganizationGroupAsync("org_01EHWNCE74X7JSDV0X3SZ3KJNY",
                                                 new GroupsCreateOrganizationGroupOptions {
                                                     Name = "Engineering",
                                                 });
```

```rust language="rust" title="Request" tab="1"
use workos::Client;
use workos::groups::CreateOrganizationGroupParams;

#[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
        .groups()
        .create_organization_group(
            "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
            CreateOrganizationGroupParams {
                name: "Engineering".into(),
                ..Default::default()
            }
        )
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "object": "group",
  "id": "group_01HXYZ123456789ABCDEFGHIJ",
  "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
  "name": "Engineering",
  "description": "The engineering team",
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z"
}
```

:::

## Delete a group

Delete a group from an organization.

:::code-group

```bash language="curl" title="Request" tab="1"
curl --request DELETE \
  --url "https://api.workos.com/organizations/org_01EHWNCE74X7JSDV0X3SZ3KJNY/groups/group_01HXYZ123456789ABCDEFGHIJ" \
  --header "Authorization: Bearer sk_example_123456789"
```

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

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

WorkOS.client.groups.delete_organization_group(
  organization_id: "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
  group_id: "group_01HXYZ123456789ABCDEFGHIJ"
)
```

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

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

client.groups.delete_organization_group(
    organization_id="org_01EHWNCE74X7JSDV0X3SZ3KJNY",
    group_id="group_01HXYZ123456789ABCDEFGHIJ",
)
```

```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.Groups().DeleteOrganizationGroup(context.Background(), "org_01EHWNCE74X7JSDV0X3SZ3KJNY", "group_01HXYZ123456789ABCDEFGHIJ")
	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
    ->groups()
    ->deleteOrganizationGroup(
        organizationId: "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
        groupId: "group_01HXYZ123456789ABCDEFGHIJ",
    );
```

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

WorkOS workos = new WorkOS("sk_example_123456789");

workos.groups.deleteOrganizationGroup(
    "org_01EHWNCE74X7JSDV0X3SZ3KJNY", "group_01HXYZ123456789ABCDEFGHIJ");
```

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

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

await client.Groups.DeleteOrganizationGroupAsync("org_01EHWNCE74X7JSDV0X3SZ3KJNY", "group_01HXYZ123456789ABCDEFGHIJ");
```

```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
        .groups()
        .delete_organization_group(
            "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
            "group_01HXYZ123456789ABCDEFGHIJ"
        )
        .await?;

    Ok(())
}
```

:::

## Get a group

Retrieve a group by its ID within an organization.

:::code-group

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

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

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

WorkOS.client.groups.get_organization_group(
  organization_id: "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
  group_id: "group_01HXYZ123456789ABCDEFGHIJ"
)
```

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

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

client.groups.get_organization_group(
    organization_id="org_01EHWNCE74X7JSDV0X3SZ3KJNY",
    group_id="group_01HXYZ123456789ABCDEFGHIJ",
)
```

```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.Groups().GetOrganizationGroup(context.Background(), "org_01EHWNCE74X7JSDV0X3SZ3KJNY", "group_01HXYZ123456789ABCDEFGHIJ")
	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
    ->groups()
    ->getOrganizationGroup(
        organizationId: "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
        groupId: "group_01HXYZ123456789ABCDEFGHIJ",
    );
```

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

WorkOS workos = new WorkOS("sk_example_123456789");

workos.groups.getOrganizationGroup(
    "org_01EHWNCE74X7JSDV0X3SZ3KJNY", "group_01HXYZ123456789ABCDEFGHIJ");
```

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

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

await client.Groups.GetOrganizationGroupAsync("org_01EHWNCE74X7JSDV0X3SZ3KJNY", "group_01HXYZ123456789ABCDEFGHIJ");
```

```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
        .groups()
        .get_organization_group(
            "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
            "group_01HXYZ123456789ABCDEFGHIJ"
        )
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "object": "group",
  "id": "group_01HXYZ123456789ABCDEFGHIJ",
  "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
  "name": "Engineering",
  "description": "The engineering team",
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z"
}
```

:::

## List Group members

Get a list of organization memberships in a group.

:::code-group

```bash language="curl" title="Request" tab="1"
curl "https://api.workos.com/organizations/org_01EHWNCE74X7JSDV0X3SZ3KJNY/groups/group_01HXYZ123456789ABCDEFGHIJ/organization-memberships" \
  --header "Authorization: Bearer sk_example_123456789"
```

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

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

WorkOS.client.groups.list_group_organization_memberships(
  organization_id: "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
  group_id: "group_01HXYZ123456789ABCDEFGHIJ"
)
```

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

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

client.groups.list_group_organization_memberships(
    organization_id="org_01EHWNCE74X7JSDV0X3SZ3KJNY",
    group_id="group_01HXYZ123456789ABCDEFGHIJ",
)
```

```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.Groups().ListOrganizationMemberships(context.Background(), "org_01EHWNCE74X7JSDV0X3SZ3KJNY", "group_01HXYZ123456789ABCDEFGHIJ")
	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
    ->groups()
    ->listGroupOrganizationMemberships(
        organizationId: "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
        groupId: "group_01HXYZ123456789ABCDEFGHIJ",
    );
```

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

WorkOS workos = new WorkOS("sk_example_123456789");

workos.groups.listGroupOrganizationMemberships(
    "org_01EHWNCE74X7JSDV0X3SZ3KJNY", "group_01HXYZ123456789ABCDEFGHIJ");
```

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

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

await client.Groups.ListOrganizationMembershipsAsync("org_01EHWNCE74X7JSDV0X3SZ3KJNY",
                                                     "group_01HXYZ123456789ABCDEFGHIJ");
```

```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
        .groups()
        .list_group_organization_memberships(
            "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
            "group_01HXYZ123456789ABCDEFGHIJ"
        )
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "object": "list",
  "data": [
    {
      "object": "organization_membership",
      "id": "om_01HXYZ123456789ABCDEFGHIJ",
      "user_id": "user_01E4ZCR3C56J083X43JQXF3JK5",
      "organization_id": "org_01EHZNVPK3SFK441A1RGBFSHRT",
      "status": "active",
      "directory_managed": false,
      "organization_name": "Acme Corp",
      "custom_attributes": {
        "department": "Engineering",
        "title": "Developer Experience Engineer",
        "location": "Brooklyn"
      },
      "created_at": "2026-01-15T12:00:00.000Z",
      "updated_at": "2026-01-15T12:00:00.000Z"
    }
  ],
  "list_metadata": {
    "before": "om_01HXYZ123456789ABCDEFGHIJ",
    "after": "om_01HXYZ987654321KJIHGFEDCBA"
  }
}
```

:::

## List groups

Get a paginated list of groups within an organization.

:::code-group

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

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

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

WorkOS.client.groups.list_organization_groups(organization_id: "org_01EHWNCE74X7JSDV0X3SZ3KJNY")
```

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

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

client.groups.list_organization_groups(organization_id="org_01EHWNCE74X7JSDV0X3SZ3KJNY")
```

```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.Groups().ListOrganizationGroups(context.Background(), "org_01EHWNCE74X7JSDV0X3SZ3KJNY")
	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
    ->groups()
    ->listOrganizationGroups(organizationId: "org_01EHWNCE74X7JSDV0X3SZ3KJNY");
```

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

WorkOS workos = new WorkOS("sk_example_123456789");

workos.groups.listOrganizationGroups("org_01EHWNCE74X7JSDV0X3SZ3KJNY");
```

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

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

await client.Groups.ListOrganizationGroupsAsync("org_01EHWNCE74X7JSDV0X3SZ3KJNY");
```

```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
        .groups()
        .list_organization_groups("org_01EHWNCE74X7JSDV0X3SZ3KJNY")
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "object": "list",
  "data": [
    {
      "object": "group",
      "id": "group_01HXYZ123456789ABCDEFGHIJ",
      "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
      "name": "Engineering",
      "description": "The engineering team",
      "created_at": "2026-01-15T12:00:00.000Z",
      "updated_at": "2026-01-15T12:00:00.000Z"
    }
  ],
  "list_metadata": {
    "before": "group_01HXYZ123456789ABCDEFGHIJ",
    "after": "group_01HXYZ987654321KJIHGFEDCBA"
  }
}
```

:::

## Remove a member from a Group

Remove an organization membership from a group.

:::code-group

```bash language="curl" title="Request" tab="1"
curl --request DELETE \
  --url "https://api.workos.com/organizations/org_01EHWNCE74X7JSDV0X3SZ3KJNY/groups/group_01HXYZ123456789ABCDEFGHIJ/organization-memberships/om_01HXYZ123456789ABCDEFGHIJ" \
  --header "Authorization: Bearer sk_example_123456789"
```

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

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

WorkOS.client.groups.delete_group_organization_membership(
  organization_id: "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
  group_id: "group_01HXYZ123456789ABCDEFGHIJ",
  om_id: "om_01HXYZ123456789ABCDEFGHIJ"
)
```

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

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

client.groups.delete_group_organization_membership(
    organization_id="org_01EHWNCE74X7JSDV0X3SZ3KJNY",
    group_id="group_01HXYZ123456789ABCDEFGHIJ",
    om_id="om_01HXYZ123456789ABCDEFGHIJ",
)
```

```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.Groups().DeleteOrganizationMembership(context.Background(), "org_01EHWNCE74X7JSDV0X3SZ3KJNY", "group_01HXYZ123456789ABCDEFGHIJ", "om_01HXYZ123456789ABCDEFGHIJ")
	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
    ->groups()
    ->deleteGroupOrganizationMembership(
        organizationId: "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
        groupId: "group_01HXYZ123456789ABCDEFGHIJ",
        omId: "om_01HXYZ123456789ABCDEFGHIJ",
    );
```

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

WorkOS workos = new WorkOS("sk_example_123456789");

workos.groups.deleteGroupOrganizationMembership("org_01EHWNCE74X7JSDV0X3SZ3KJNY",
    "group_01HXYZ123456789ABCDEFGHIJ",
    "om_01HXYZ123456789ABCDEFGHIJ");
```

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

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

await client.Groups.DeleteOrganizationMembershipAsync("org_01EHWNCE74X7JSDV0X3SZ3KJNY",
                                                      "group_01HXYZ123456789ABCDEFGHIJ",
                                                      "om_01HXYZ123456789ABCDEFGHIJ");
```

```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
        .groups()
        .delete_group_organization_membership(
            "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
            "group_01HXYZ123456789ABCDEFGHIJ",
            "om_01HXYZ123456789ABCDEFGHIJ"
        )
        .await?;

    Ok(())
}
```

:::

## Update Group members

Adds and removes organization memberships for a group in a single atomic operation. Organization memberships not listed in `add` or `remove` are left unchanged. Adding a member that is already in the group or removing a member that isn't in the group has no effect. A membership listed in both `add` and `remove` is rejected. `add` and `remove` must contain between 1 and 100 entries combined.

:::code-group

```bash language="curl" title="Request" tab="1"
curl --request PATCH \
  --url "https://api.workos.com/organizations/org_01EHWNCE74X7JSDV0X3SZ3KJNY/groups/group_01HXYZ123456789ABCDEFGHIJ/organization-memberships" \
  --header "Authorization: Bearer sk_example_123456789" \
  --header "Content-Type: application/json" \
  -d @- <<'BODY'
    {
        "add": [
            "om_01HXYZ123456789ABCDEFGHIJ"
        ],
        "remove": [
            "om_01HXYZ987654321ABCDEFGHIJ"
        ]
    }
BODY
```

```rb language="ruby" title="Request" tab="1"
# workos:manual - include add/remove; oagen omits optional body params
require "workos"

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

WorkOS.client.groups.update_group_organization_memberships(
  organization_id: "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
  group_id: "group_01HXYZ123456789ABCDEFGHIJ",
  add: ["om_01HXYZ123456789ABCDEFGHIJ"],
  remove: ["om_01HXYZ987654321ABCDEFGHIJ"]
)
```

```py language="python" title="Request" tab="1"
# workos:manual - include add/remove; oagen omits optional body params
from workos import WorkOSClient

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

client.groups.update_group_organization_memberships(
    organization_id="org_01EHWNCE74X7JSDV0X3SZ3KJNY",
    group_id="group_01HXYZ123456789ABCDEFGHIJ",
    add=["om_01HXYZ123456789ABCDEFGHIJ"],
    remove=["om_01HXYZ987654321ABCDEFGHIJ"],
)
```

```go language="go" title="Request" tab="1"
// workos:manual - include add/remove; oagen omits optional body params
package main

import (
	"context"

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

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

	_, err := client.Groups().UpdateOrganizationMemberships(context.Background(), "org_01EHWNCE74X7JSDV0X3SZ3KJNY", "group_01HXYZ123456789ABCDEFGHIJ", &workos.GroupsUpdateOrganizationMembershipsParams{
		Add:    []string{"om_01HXYZ123456789ABCDEFGHIJ"},
		Remove: []string{"om_01HXYZ987654321ABCDEFGHIJ"},
	})
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php
// workos:manual - include add/remove; oagen omits optional body params

use WorkOS\WorkOS;

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

$workos
    ->groups()
    ->updateGroupOrganizationMemberships(
        organizationId: "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
        groupId: "group_01HXYZ123456789ABCDEFGHIJ",
        add: ["om_01HXYZ123456789ABCDEFGHIJ"],
        remove: ["om_01HXYZ987654321ABCDEFGHIJ"],
    );
```

```java language="java" title="Request" tab="1"
// workos:manual - include add/remove; oagen omits optional body params
import com.workos.WorkOS;
import com.workos.groups.GroupsApi.UpdateGroupOrganizationMembershipsOptions;

WorkOS workos = new WorkOS("sk_example_123456789");

UpdateGroupOrganizationMembershipsOptions options =
    UpdateGroupOrganizationMembershipsOptions.builder()
        .add(List.of("om_01HXYZ123456789ABCDEFGHIJ"))
        .remove(List.of("om_01HXYZ987654321ABCDEFGHIJ"))
        .build();

workos.groups.updateGroupOrganizationMemberships(
    "org_01EHWNCE74X7JSDV0X3SZ3KJNY", "group_01HXYZ123456789ABCDEFGHIJ", options);
```

```cs language="dotnet" title="Request" tab="1"
// workos:manual - include add/remove; oagen omits optional body params
using WorkOS;

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

await client.Groups.UpdateOrganizationMembershipsAsync("org_01EHWNCE74X7JSDV0X3SZ3KJNY",
                                                       "group_01HXYZ123456789ABCDEFGHIJ",
                                                       new GroupsUpdateOrganizationMembershipsOptions {
                                                           Add = new[] { "om_01HXYZ123456789ABCDEFGHIJ" },
                                                           Remove = new[] { "om_01HXYZ987654321ABCDEFGHIJ" },
                                                       });
```

```rust language="rust" title="Request" tab="1"
// workos:manual - include add/remove; oagen omits optional body params
use workos::Client;
use workos::groups::UpdateGroupOrganizationMembershipsParams;

#[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
        .groups()
        .update_group_organization_memberships(
            "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
            "group_01HXYZ123456789ABCDEFGHIJ",
            UpdateGroupOrganizationMembershipsParams {
                add: vec!["om_01HXYZ123456789ABCDEFGHIJ".into()],
                remove: vec!["om_01HXYZ987654321ABCDEFGHIJ".into()],
                ..Default::default()
            }
        )
        .await?;

    Ok(())
}
```

:::

## Update a group

Update an existing group. Only the fields provided in the request body will be updated.

:::code-group

```bash language="curl" title="Request" tab="1"
curl --request PATCH \
  --url "https://api.workos.com/organizations/org_01EHWNCE74X7JSDV0X3SZ3KJNY/groups/group_01HXYZ123456789ABCDEFGHIJ" \
  --header "Authorization: Bearer sk_example_123456789" \
  --header "Content-Type: application/json" \
  -d @- <<'BODY'
    {
        "name": "Engineering",
        "description": "The engineering team"
    }
BODY
```

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

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

WorkOS.client.groups.update_organization_group(
  organization_id: "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
  group_id: "group_01HXYZ123456789ABCDEFGHIJ"
)
```

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

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

client.groups.update_organization_group(
    organization_id="org_01EHWNCE74X7JSDV0X3SZ3KJNY",
    group_id="group_01HXYZ123456789ABCDEFGHIJ",
)
```

```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.Groups().UpdateOrganizationGroup(context.Background(), "org_01EHWNCE74X7JSDV0X3SZ3KJNY", "group_01HXYZ123456789ABCDEFGHIJ")
	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
    ->groups()
    ->updateOrganizationGroup(
        organizationId: "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
        groupId: "group_01HXYZ123456789ABCDEFGHIJ",
    );
```

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

WorkOS workos = new WorkOS("sk_example_123456789");

workos.groups.updateOrganizationGroup(
    "org_01EHWNCE74X7JSDV0X3SZ3KJNY", "group_01HXYZ123456789ABCDEFGHIJ");
```

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

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

await client.Groups.UpdateOrganizationGroupAsync("org_01EHWNCE74X7JSDV0X3SZ3KJNY", "group_01HXYZ123456789ABCDEFGHIJ");
```

```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
        .groups()
        .update_organization_group(
            "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
            "group_01HXYZ123456789ABCDEFGHIJ"
        )
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "object": "group",
  "id": "group_01HXYZ123456789ABCDEFGHIJ",
  "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
  "name": "Engineering",
  "description": "The engineering team",
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z"
}
```

:::

### group

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | "group" | Yes | The Group object. |
| `id` | string | Yes | The unique ID of the Group. |
| `organization_id` | string | Yes | The ID of the Organization the Group belongs to. |
| `name` | string | Yes | The name of the Group. |
| `description` | string | No | An optional description of the Group. |
| `created_at` | string | Yes | An ISO 8601 timestamp. |
| `updated_at` | string | Yes | An ISO 8601 timestamp. |

### POST /organizations/{organizationId}/groups/{groupId}/organization-memberships

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `organization_membership_id` | string | Yes | The ID of the Organization Membership to add to the group. |

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `organizationId` | string | Yes | Unique identifier of the Organization. |
| `groupId` | string | Yes | Unique identifier of the Group. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `group` | object | The Group object. |

### POST /organizations/{organizationId}/groups

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes | The name of the Group. |
| `description` | string | No | An optional description of the Group. |

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `organizationId` | string | Yes | The ID of the organization. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `group` | object | The Group object. |

### DELETE /organizations/{organizationId}/groups/{groupId}

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `organizationId` | string | Yes | The ID of the organization. |
| `groupId` | string | Yes | The ID of the group. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `empty` | empty | Returns an empty response on success. |

### GET /organizations/{organizationId}/groups/{groupId}

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `organizationId` | string | Yes | The ID of the organization. |
| `groupId` | string | Yes | The ID of the group. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `group` | object | The Group object. |

### GET /organizations/{organizationId}/groups/{groupId}/organization-memberships

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `organizationId` | string | Yes | Unique identifier of the Organization. |
| `groupId` | string | Yes | Unique identifier of the Group. |
| `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`. |

### GET /organizations/{organizationId}/groups

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `organizationId` | string | Yes | The ID of the organization. |
| `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`. |
| `search` | string | No | Search groups by name or by group ID. |

### DELETE /organizations/{organizationId}/groups/{groupId}/organization-memberships/{omId}

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `organizationId` | string | Yes | Unique identifier of the Organization. |
| `groupId` | string | Yes | Unique identifier of the Group. |
| `omId` | string | Yes | Unique identifier of the Organization Membership. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `empty` | empty | Returns an empty response on success. |

### PATCH /organizations/{organizationId}/groups/{groupId}/organization-memberships

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `add` | string[] | No | The IDs of the organization memberships to add to the group. Adding a membership that's already in the group has no effect. Defaults to `[]`. |
| `remove` | string[] | No | The IDs of the organization memberships to remove from the group. Removing a membership that isn't in the group has no effect. Defaults to `[]`. |

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `organizationId` | string | Yes | Unique identifier of the Organization. |
| `groupId` | string | Yes | Unique identifier of the Group. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `empty` | empty | Returns an empty response on success. |

### PATCH /organizations/{organizationId}/groups/{groupId}

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | No | The name of the Group. |
| `description` | string | No | An optional description of the Group. |

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `organizationId` | string | Yes | The ID of the organization. |
| `groupId` | string | Yes | The ID of the group. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `group` | object | The Group object. |