> For the complete documentation index, see [llms.txt](/docs/llms.txt)

# Groups | FusionAuth Docs

An overview of FusionAuth Groups.

# Groups

There are a few reasons you may want to use a FusionAuth Group.

The first use is to logically group one or more users within a Tenant. Once a User is a member of a Group they may be identified as a member of the Group and retrieved using the [User Search API](/docs/apis/users/search).

The second reason you may use a Group is to manage Application Role assignment. A Group may be assigned roles from one or more Applications, a member of this Group will be dynamically assigned these roles if they have a registration for the Application.

## Core Concepts Relationships[#](#core-concepts-relationships)

Below is a visual reminder of the relationships between FusionAuth's primary core concepts.

![Diagram showing Groups used within FusionAuth](/img/docs/get-started/core-concepts/core-concepts-relationships-groups.png)

## Examples[#](#examples)

Here are some examples of using Groups.

### Grouping Users[#](#grouping-users)

If you are performing educational marketing activities and driving self-service signups, you can pull the source of a signup off a URL parameter and place it into the **user.data** field using a [custom registration form](/docs/lifecycle/register-users/advanced-registration-forms). On user creation, you could add them to a variety of Groups based on the attributes of the webinar using a webhook.

For example:

*   Date of signup
*   Online or offline presentation
*   Presenter
*   Version of webinar

You could then use these Groups for cohort analysis later to see which users best converted to paying customers.

This usage of Groups can be similarly performed by the **user.data** custom data fields. However, with this approach, each Group can have metadata in the **group.data** field that includes information about the Group and how and why users were placed in it. The use of a separate grouping object with its own metadata can be useful.

### Assigning Roles[#](#assigning-roles)

You could create a Group called `Admin`, and assign this group the admin role from each of your applications.

A more detailed example:

Suppose the Pied Piper Application has two roles: `admin` and `member`. The Hooli Application has one role `superadmin`.

Richard has a registration in Pied Piper and Nelson has a registration in Hooli.

Finally, there's a group called `Admin Group` which has the application roles of `admin` from Pied Piper and `superadmin` from Hooli.

If you add Richard to the `Admin Group`, he will receive the role `admin` in Pied Piper, but not `superadmin` (because they aren't registered for Hooli, so he can't get the role for that application).

## Group Membership In Tokens[#](#group-membership-in-tokens)

Sometimes you want membership information in an access token generated by a login event. This data is not directly available in the lambda arguments.

However, you can do this by using [Lambda HTTP Connect](/docs/extend/code/lambdas/lambda-remote-api-calls) to request memberships using the [Group API](/docs/apis/groups) from within a [JWT Populate Lambda](/docs/extend/code/lambdas/jwt-populate). Here's an example of such a lambda.

```
function populate(jwt, user, registration) {
  var response = fetch("http://localhost:9012/api/group", {
    method: "GET",
    headers: {
      "Authorization": "bf69486b-4733-4470-a592-f1bfce7af580"
    }
  });

  if (response.status === 200) {
    // a successful response as defined in the Groups API
    var jsonResponse = JSON.parse(response.body);
    jwt.groups = jsonResponse.groups;
  } else {
    jwt.groups = [];
  }
}
```

This feature is only available in Essentials or Enterprise plans. To learn more, see [our pricing page](/pricing).

## Admin UI[#](#admin-ui)

### Create a Group[#](#create-a-group)

Click on Settings -> Groups from the main menu to add a Group. At a minimum, you must provide a **Name** for the Group and the **Tenant** it belongs to.

You may apply Application roles from the various Applications in this Group's Tenant.

![Create a Group](/img/docs/get-started/core-concepts/create-group.png)

#### Form Fields[#](#form-fields)

`Id`optional

The Group Id.

`Name`required

The Group name.

`Tenant`required

The Tenant the Group will be scoped to.

`Application Roles`optional

The selected Application Roles will be assumed by members of this Group.

## Limits[#](#limits)

Groups can only contain Users, not other Groups.

Groups are always contained within a Tenant, and cannot span Tenants.