# Groups

Groups let you manage access for multiple subjects at once. Instead of granting permissions to each user or client individually, you can add them to a group and apply policies to the group as a whole.

## When to use groups

- A team of users needs the same access to a subscription
- You want to onboard new users with a predefined permission set
- You need to revoke access for an entire team in one step


## List groups

Retrieve all subject groups in your tenant:

## Create a group

**Response:**


```json
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "displayName": "Finance Team",
  "subjectId": "group-7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "type": "Group"
}
```

Store the `id` - you will need it for all subsequent group operations. The `subjectId` is the group's subject identifier used when creating policies targeting the group.

Applying policies to groups
To grant a group permissions, create a policy with the group's `subjectId` as the `subject`. See the [Policies guide](/apis/platform/iam/guides/policies) for details.

## Add members to a group

You can add one or more subjects (users or clients) to a group in a single request:

Example request body:


```json
{
  "subjectIds": [
    "user-550e8400-e29b-41d4-a716-446655440000",
    "user-6ba7b810-9dad-11d1-80b4-00c04fd430c8"
  ]
}
```

Members immediately inherit all policies assigned to the group.

## List group members

Retrieve all subjects within a group:

## Remove a member from a group

The removed subject immediately loses any permissions that were inherited through this group. Permissions granted directly to the subject (via other policies) are unaffected.

## View group permissions

See all policies currently assigned to a group:

## Delete a group

Warning
Deleting a group removes all members from the group and deletes all policies associated with the group's subject ID. Members lose any permissions they inherited from this group.