> For the complete documentation index, see [llms.txt](https://docs.enclaive.cloud/vault/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.enclaive.cloud/vault/api/secrets-engines/identity/group.md).

# group

**NOTE:** Be careful in granting permissions to non-readonly identity group endpoints. If a user can modify group membership, they can add their entity to a group with higher privileges.

### Create a group <a href="#create-a-group" id="create-a-group"></a>

This endpoint creates or updates a Group.

| Method | Path              |
| ------ | ----------------- |
| `POST` | `/identity/group` |

#### Parameters <a href="#parameters" id="parameters"></a>

* `name` `(string: entity-<UUID>)` – Name of the group. If set (and ID is not set), updates the corresponding existing group.
* `id` `(string: <optional>)` - ID of the group. If set, updates the corresponding existing group.
* `type` `(string: "internal")` - Type of the group, `internal` or `external`. Defaults to `internal`.
* `metadata` `(key-value-map: {})` – Metadata to be associated with the group.
* `policies` `(list of strings: [])` – Policies to be tied to the group.
* `member_group_ids` `(list of strings: [])` - Group IDs to be assigned as group members.
* `member_entity_ids` `(list of strings: [])` - Entity IDs to be assigned as group members.

#### Sample payload <a href="#sample-payload" id="sample-payload"></a>

```json
{
  "metadata": {
    "hello": "world"
  },
  "policies": ["grouppolicy1", "grouppolicy2"]
}
```

#### Sample request <a href="#sample-request" id="sample-request"></a>

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/identity/group
```

#### Sample response <a href="#sample-response" id="sample-response"></a>

```json
{
  "data": {
    "id": "363926d8-dd8b-c9f0-21f8-7b248be80ce1",
    "name": "group_ab813d63"
  }
}
```

### Read group by ID <a href="#read-group-by-id" id="read-group-by-id"></a>

This endpoint queries the group by its identifier.

| Method | Path                     |
| ------ | ------------------------ |
| `GET`  | `/identity/group/id/:id` |

#### Parameters <a href="#parameters-1" id="parameters-1"></a>

* `id` `(string: <required>)` – Identifier of the group.

#### Sample request <a href="#sample-request-1" id="sample-request-1"></a>

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/identity/group/id/363926d8-dd8b-c9f0-21f8-7b248be80ce1
```

#### Sample response <a href="#sample-response-1" id="sample-response-1"></a>

```json
{
  "data": {
    "alias": {},
    "creation_time": "2017-11-13T19:36:47.102945Z",
    "id": "363926d8-dd8b-c9f0-21f8-7b248be80ce1",
    "last_update_time": "2017-11-13T19:36:47.102945Z",
    "member_entity_ids": [],
    "member_group_ids": null,
    "metadata": {
      "hello": "world"
    },
    "modify_index": 1,
    "name": "group_ab813d63",
    "policies": ["grouppolicy1", "grouppolicy2"],
    "type": "internal"
  }
}
```

### Update group by ID <a href="#update-group-by-id" id="update-group-by-id"></a>

This endpoint is used to update an existing group.

| Method | Path                     |
| ------ | ------------------------ |
| `POST` | `/identity/group/id/:id` |

#### Parameters <a href="#parameters-2" id="parameters-2"></a>

* `id` `(string: <required>)` – Identifier of the entity.
* `name` `(string: entity-<UUID>)` – Name of the group.
* `type` `(string: "internal")` - Type of the group, `internal` or `external`. Defaults to `internal`.
* `metadata` `(key-value-map: {})` – Metadata to be associated with the group.
* `policies` `(list of strings: [])` – Policies to be tied to the group.
* `member_group_ids` `(list of strings: [])` - Group IDs to be assigned as group members.
* `member_entity_ids` `(list of strings: [])` - Entity IDs to be assigned as group members.

#### Sample payload <a href="#sample-payload-1" id="sample-payload-1"></a>

```json
{
  "name": "testgroupname",
  "metadata": {
    "hello": "everyone"
  },
  "policies": ["grouppolicy2", "grouppolicy3"]
}
```

#### Sample request <a href="#sample-request-2" id="sample-request-2"></a>

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/identity/group/id/363926d8-dd8b-c9f0-21f8-7b248be80ce1
```

#### Sample response <a href="#sample-response-2" id="sample-response-2"></a>

```json
{
  "data": {
    "id": "363926d8-dd8b-c9f0-21f8-7b248be80ce1",
    "name": "testgroupname"
  }
}
```

### Delete group by ID <a href="#delete-group-by-id" id="delete-group-by-id"></a>

This endpoint deletes a group.

| Method   | Path                     |
| -------- | ------------------------ |
| `DELETE` | `/identity/group/id/:id` |

### Parameters <a href="#parameters-3" id="parameters-3"></a>

* `id` `(string: <required>)` – Identifier of the group.

#### Sample request <a href="#sample-request-3" id="sample-request-3"></a>

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/identity/group/id/363926d8-dd8b-c9f0-21f8-7b248be80ce1
```

### List groups by ID <a href="#list-groups-by-id" id="list-groups-by-id"></a>

This endpoint returns a list of available groups by their identifiers.

| Method | Path                           |
| ------ | ------------------------------ |
| `LIST` | `/identity/group/id`           |
| `GET`  | `/identity/group/id?list=true` |

#### Sample request <a href="#sample-request-4" id="sample-request-4"></a>

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/identity/group/id
```

#### Sample response <a href="#sample-response-3" id="sample-response-3"></a>

```json
{
  "data": {
    "keys": [
      "052567cf-1580-6f20-50c8-d38bc46dae6e",
      "26da8035-6691-b89e-67ac-ebf9ea7f9893",
      "363926d8-dd8b-c9f0-21f8-7b248be80ce1",
      "5c4a5720-7408-c113-1dcc-9ede725d0ac8",
      "d55e0f34-5c16-38ae-87af-324c9b656c43",
      "e4e56e04-0dec-9b68-9b20-a450975d898e"
    ]
  }
}
```

### Create/Update group by name <a href="#create-update-group-by-name" id="create-update-group-by-name"></a>

This endpoint is used to create or update a group by its name.

| Method | Path                         |
| ------ | ---------------------------- |
| `POST` | `/identity/group/name/:name` |

#### Parameters <a href="#parameters-4" id="parameters-4"></a>

* `name` `(string: entity-<UUID>)` – Name of the group.
* `type` `(string: "internal")` - Type of the group, `internal` or `external`. Defaults to `internal`.
* `metadata` `(key-value-map: {})` – Metadata to be associated with the group.
* `policies` `(list of strings: [])` – Policies to be tied to the group.
* `member_group_ids` `(list of strings: [])` - Group IDs to be assigned as group members.
* `member_entity_ids` `(list of strings: [])` - Entity IDs to be assigned as group members.

#### Sample payload <a href="#sample-payload-2" id="sample-payload-2"></a>

```json
{
  "metadata": {
    "hello": "everyone"
  },
  "policies": ["grouppolicy2", "grouppolicy3"]
}
```

#### Sample request <a href="#sample-request-5" id="sample-request-5"></a>

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/identity/group/name/testgroupname
```

#### Sample response <a href="#sample-response-4" id="sample-response-4"></a>

```json
{
  "request_id": "b98b4a3d-a9f1-e151-11e1-ad91cfb08351",
  "lease_id": "",
  "lease_duration": 0,
  "renewable": false,
  "data": {
    "id": "5a3a04a0-0c3a-a4c3-74e8-26b1adbeaece",
    "name": "testgroupname"
  },
  "warnings": null
}
```

### Read group by name <a href="#read-group-by-name" id="read-group-by-name"></a>

This endpoint queries the group by its name.

| Method | Path                         |
| ------ | ---------------------------- |
| `GET`  | `/identity/group/name/:name` |

#### Parameters <a href="#parameters-5" id="parameters-5"></a>

* `name` `(string: <required>)` – Name of the group.

#### Sample request <a href="#sample-request-6" id="sample-request-6"></a>

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/identity/group/name/testgroupname
```

#### Sample response <a href="#sample-response-5" id="sample-response-5"></a>

```json
{
  "data": {
    "alias": {},
    "creation_time": "2018-09-19T22:02:04.395128091Z",
    "id": "5a3a04a0-0c3a-a4c3-74e8-26b1adbeaece",
    "last_update_time": "2018-09-19T22:02:04.395128091Z",
    "member_entity_ids": [],
    "member_group_ids": null,
    "metadata": {
      "foo": "bar"
    },
    "modify_index": 1,
    "name": "testgroupname",
    "parent_group_ids": null,
    "policies": ["grouppolicy1", "grouppolicy2"],
    "type": "internal"
  }
}
```

### Delete group by name <a href="#delete-group-by-name" id="delete-group-by-name"></a>

This endpoint deletes a group, given its name.

| Method   | Path                         |
| -------- | ---------------------------- |
| `DELETE` | `/identity/group/name/:name` |

### Parameters <a href="#parameters-6" id="parameters-6"></a>

* `name` `(string: <required>)` – Name of the group.

#### Sample request <a href="#sample-request-7" id="sample-request-7"></a>

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/identity/group/name/testgroupname
```

### List groups by name <a href="#list-groups-by-name" id="list-groups-by-name"></a>

This endpoint returns a list of available groups by their names.

| Method | Path                             |
| ------ | -------------------------------- |
| `LIST` | `/identity/group/name`           |
| `GET`  | `/identity/group/name?list=true` |

#### Sample request <a href="#sample-request-8" id="sample-request-8"></a>

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/identity/group/name
```

#### Sample response <a href="#sample-response-6" id="sample-response-6"></a>

```json
{
  "data": {
    "keys": ["testgroupname"]
  }
}
```