Groups

Groups let you organize organization memberships into named collections within an organization. An organization membership represents a single user’s access to an organization. A group represents a logical subset of members. A user can belong to zero or more groups.

Groups are native to WorkOS and managed by your application through the API. This is distinct from directory groups, which are provisioned by an external identity provider through SCIM.

Groups give you a way to model users within teams, departments, or any organizational unit. For example, you might create an “Engineering” group or a “Finance” group to reflect your customer’s organizational structure.

Today, groups provide a foundation for organizing members. In the future, groups will unlock additional capabilities across the WorkOS platform, including:

• Group-based role assignment – assign roles to a group and have them apply to all of its members.
• Scoped access control – grant resource scoped roles from FGA to a group so all members inherit access to the same resources.
• IdP group sync – keep groups in sync with your customer’s identity provider.

Groups are managed entirely through the API. You can view the full Group object in the API reference.

Create a group within an organization using the create group API. Each group has a name and belongs to a single organization. You can update a group’s name using the update group API, or remove it entirely with the delete group API.

Add an organization membership to a group using the add group member API. Adding a member that already belongs to the group is a no-op, the API returns successfully without creating a duplicate.

Retrieve a paginated list of organization memberships in a group using the list group members API.

Retrieve a paginated list of groups that an organization membership belongs to using the list groups for organization membership API.

Remove an organization membership from a group using the remove group member API. Removing a member deletes the group membership. The organization membership and the group are unaffected.

Group memberships are automatically cleaned up when the underlying organization membership or organization is removed:

• Deleting an organization membership removes group memberships for the organization membership.
• Deleting a user removes all of the user’s organization memberships, which in turn removes all associated group memberships.
• Deleting an organization removes all group memberships before removing the groups themselves.

Group lifecycle changes emit group.* events that can be used to trigger workflows in your application or received via webhooks. You can view these events on the events page of the dashboard.