Group

A Group is a collection of Organization Memberships within an Organization. Use Groups to organize users into organizational units.

To list the groups that a specific Organization Membership belongs to, use List Groups.

Example Group

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"
}

`group`

Add a member to a Group

Add an organization membership to a group.

cURL

 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

 {
  "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"
}

Feature flagged

POST

`/organizations/:organizationId/groups/:groupId/organization-memberships`

`Parameters`

`Returns`

Create a group

Create a new group within an organization.

cURL

 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

 {
  "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"
}

Feature flagged

POST

`/organizations/:organizationId/groups`

`Parameters`

`Returns`

Delete a group

Delete a group from an organization.

cURL

 curl --request DELETE \
  --url "https://api.workos.com/organizations/org_01EHWNCE74X7JSDV0X3SZ3KJNY/groups/group_01HXYZ123456789ABCDEFGHIJ" \
  --header "Authorization: Bearer sk_example_123456789"

Feature flagged

DELETE

`/organizations/:organizationId/groups/:groupId`

`Parameters`

`Returns`

Get a group

Retrieve a group by its ID within an organization.

cURL

 curl "https://api.workos.com/organizations/org_01EHWNCE74X7JSDV0X3SZ3KJNY/groups/group_01HXYZ123456789ABCDEFGHIJ" \
  --header "Authorization: Bearer sk_example_123456789"

 {
  "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"
}

Feature flagged

GET

`/organizations/:organizationId/groups/:groupId`

`Parameters`

`Returns`

List groups

Get a paginated list of groups within an organization.

cURL

 curl "https://api.workos.com/organizations/org_01EHWNCE74X7JSDV0X3SZ3KJNY/groups" \
  --header "Authorization: Bearer sk_example_123456789"

 {
  "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"
  }
}

Feature flagged

GET

`/organizations/:organizationId/groups`

`Parameters`

`Returns` `object`

List Group members

Get a list of organization memberships in a group.

cURL

 curl "https://api.workos.com/organizations/org_01EHWNCE74X7JSDV0X3SZ3KJNY/groups/group_01HXYZ123456789ABCDEFGHIJ/organization-memberships" \
  --header "Authorization: Bearer sk_example_123456789"

 {
  "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"
  }
}

Feature flagged

GET

`/organizations/:organizationId/groups/:groupId/organization-memberships`

`Parameters`

`Returns` `object`

Remove a member from a Group

Remove an organization membership from a group.

cURL

 curl --request DELETE \
  --url "https://api.workos.com/organizations/org_01EHWNCE74X7JSDV0X3SZ3KJNY/groups/group_01HXYZ123456789ABCDEFGHIJ/organization-memberships/om_01HXYZ123456789ABCDEFGHIJ" \
  --header "Authorization: Bearer sk_example_123456789"

Feature flagged

DELETE

`/organizations/:organizationId/groups/:groupId/organization-memberships/:omId`

`Parameters`

`Returns`

Update a group

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

cURL

 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

 {
  "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"
}

Feature flagged

PATCH

Group

group

object: "group"

id: string

organization_id: string

name: string

description?: string

created_at: string

updated_at: string

Add a member to a Group

/organizations/:organizationId/groups/:groupId/organization-memberships

organization_membership_id: string

Parameters

organizationId: string

groupId: string

Returns

group: object

Create a group

/organizations/:organizationId/groups

name: string

description?: string

Parameters

organizationId: string

Returns

group: object

Delete a group

/organizations/:organizationId/groups/:groupId

Parameters

organizationId: string

groupId: string

Returns

empty: empty

Get a group

/organizations/:organizationId/groups/:groupId

Parameters

organizationId: string

groupId: string

Returns

group: object

List groups

/organizations/:organizationId/groups

Parameters

organizationId: string

before?: string

after?: string

limit?: integer

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

Returns object

object: "list"

data: object[]

list_metadata: object

List Group members

/organizations/:organizationId/groups/:groupId/organization-memberships

Parameters

organizationId: string

groupId: string

before?: string

after?: string

limit?: integer

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

Returns object

object: "list"

data: object[]

list_metadata: object

Remove a member from a Group

/organizations/:organizationId/groups/:groupId/organization-memberships/:omId

Parameters

organizationId: string

groupId: string

omId: string

Returns

empty: empty

Update a group

/organizations/:organizationId/groups/:groupId

name?: string

description?: string

Parameters

organizationId: string

groupId: string

Returns

`group`

`/organizations/:organizationId/groups/:groupId/organization-memberships`

`Parameters`

`Returns`

`/organizations/:organizationId/groups`

`Parameters`

`Returns`

`/organizations/:organizationId/groups/:groupId`

`Parameters`

`Returns`

`/organizations/:organizationId/groups/:groupId`

`Parameters`

`Returns`

`/organizations/:organizationId/groups`

`Parameters`

`Returns` `object`

`/organizations/:organizationId/groups/:groupId/organization-memberships`

`Parameters`

`Returns` `object`

`/organizations/:organizationId/groups/:groupId/organization-memberships/:omId`

`Parameters`

`Returns`

`/organizations/:organizationId/groups/:groupId`

`Parameters`

`Returns`