# 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"]
  }
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.enclaive.cloud/vault/api/secrets-engines/identity/group.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.