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.
{ "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" }
groupGet a paginated list of groups within an organization.
curl "https://api.workos.com/organizations/org_01EHWNCE74X7JSDV0X3SZ3KJNY/groups" \ --header "Authorization: Bearer sk_example_123456789"
GET/organizationsParameters Returns objectCreate a new group within an organization.
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
POST/organizationsParameters Returns Retrieve a group by its ID within an organization.
curl "https://api.workos.com/organizations/org_01EHWNCE74X7JSDV0X3SZ3KJNY/groups/group_01HXYZ123456789ABCDEFGHIJ" \ --header "Authorization: Bearer sk_example_123456789"
GET/organizationsParameters Returns Update an existing group. Only the fields provided in the request body will be updated.
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
PATCH/organizationsParameters Returns Delete a group from an organization.
curl --request DELETE \ --url "https://api.workos.com/organizations/org_01EHWNCE74X7JSDV0X3SZ3KJNY/groups/group_01HXYZ123456789ABCDEFGHIJ" \ --header "Authorization: Bearer sk_example_123456789"
DELETE/organizationsParameters Returns Get a list of organization memberships in a group.
curl "https://api.workos.com/organizations/org_01EHWNCE74X7JSDV0X3SZ3KJNY/groups/group_01HXYZ123456789ABCDEFGHIJ/organization-memberships" \ --header "Authorization: Bearer sk_example_123456789"
GET/organizationsParameters Returns objectAdd an organization membership to a group.
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
POST/organizationsParameters Returns Remove an organization membership from a group.
curl --request DELETE \ --url "https://api.workos.com/organizations/org_01EHWNCE74X7JSDV0X3SZ3KJNY/groups/group_01HXYZ123456789ABCDEFGHIJ/organization-memberships/om_01HXYZ123456789ABCDEFGHIJ" \ --header "Authorization: Bearer sk_example_123456789"
DELETE/organizationsParameters Returns