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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.