mirror of
https://github.com/hashicorp/vault.git
synced 2026-07-01 21:40:07 -04:00
b659e94a3b
* Doc updates and API refactoring * fix tests * change metadata fieldtype to TypeKVPairs * Give example for TypeKVPairs in CLI for metadata * Update API docs examples to reflect the native expected value for TypeKVPairs * Don't mention comma separation in the docs for TypeCommaStringSlice * s/groups/group; s/entities/entity; s/entity-aliases/entity-alias; s/group-aliases/group-alias * Address review feedback * Fix formatting * fix sidebar links
230 lines
5.1 KiB
Markdown
230 lines
5.1 KiB
Markdown
---
|
||
layout: "api"
|
||
page_title: "Identity Secret Backend: Group - HTTP API"
|
||
sidebar_current: "docs-http-secret-identity-group"
|
||
description: |-
|
||
This is the API documentation for managing groups in the identity store.
|
||
---
|
||
|
||
## Create a Group
|
||
|
||
This endpoint creates or updates a Group.
|
||
|
||
| Method | Path | Produces |
|
||
| :------- | :------------------ | :----------------------|
|
||
| `POST` | `/identity/group` | `200 application/json` |
|
||
|
||
### Parameters
|
||
|
||
- `name` `(string: entity-<UUID>)` – Name of the 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
|
||
|
||
```json
|
||
{
|
||
"metadata": {
|
||
"hello": "world"
|
||
},
|
||
"policies": ["grouppolicy1", "grouppolicy2"]
|
||
}
|
||
```
|
||
|
||
### Sample Request
|
||
|
||
```
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request POST \
|
||
--data @payload.json \
|
||
https://vault.rocks/v1/identity/group
|
||
```
|
||
|
||
### Sample Response
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"id": "363926d8-dd8b-c9f0-21f8-7b248be80ce1",
|
||
"name": "group_ab813d63"
|
||
}
|
||
}
|
||
```
|
||
|
||
## Read Group by ID
|
||
|
||
This endpoint queries the group by its identifier.
|
||
|
||
| Method | Path | Produces |
|
||
| :------- | :-------------------------- | :--------------------- |
|
||
| `GET` | `/identity/group/id/:id` | `200 application/json` |
|
||
|
||
### Parameters
|
||
|
||
- `id` `(string: <required>)` – Identifier of the group.
|
||
|
||
### Sample Request
|
||
|
||
```
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
https://vault.rocks/v1/identity/group/id/363926d8-dd8b-c9f0-21f8-7b248be80ce1
|
||
```
|
||
|
||
### Sample Response
|
||
|
||
```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
|
||
|
||
This endpoint is used to update an existing group.
|
||
|
||
| Method | Path | Produces |
|
||
| :------- | :-------------------------- | :--------------------- |
|
||
| `POST` | `/identity/group/id/:id` | `200 application/json` |
|
||
|
||
### Parameters
|
||
|
||
- `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
|
||
|
||
```json
|
||
{
|
||
"name": "testgroupname",
|
||
"metadata": {
|
||
"hello": "everyone"
|
||
},
|
||
"policies": ["grouppolicy2", "grouppolicy3"]
|
||
}
|
||
```
|
||
|
||
### Sample Request
|
||
|
||
```
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request POST \
|
||
--data @payload.json \
|
||
https://vault.rocks/v1/identity/group/id/363926d8-dd8b-c9f0-21f8-7b248be80ce1
|
||
```
|
||
|
||
### Sample Response
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"id": "363926d8-dd8b-c9f0-21f8-7b248be80ce1",
|
||
"name": "testgroupname"
|
||
}
|
||
}
|
||
```
|
||
|
||
## Delete Group by ID
|
||
|
||
This endpoint deletes a group.
|
||
|
||
| Method | Path | Produces |
|
||
| :--------- | :------------------------- | :----------------------|
|
||
| `DELETE` | `/identity/group/id/:id` | `204 (empty body)` |
|
||
|
||
## Parameters
|
||
|
||
- `id` `(string: <required>)` – Identifier of the group.
|
||
|
||
### Sample Request
|
||
|
||
```
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request DELETE \
|
||
https://vault.rocks/v1/identity/group/id/363926d8-dd8b-c9f0-21f8-7b248be80ce1
|
||
```
|
||
|
||
## List Groups by ID
|
||
|
||
This endpoint returns a list of available groups by their identifiers.
|
||
|
||
| Method | Path | Produces |
|
||
| :------- | :----------------------------- | :--------------------- |
|
||
| `LIST` | `/identity/group/id` | `200 application/json` |
|
||
| `GET` | `/identity/group/id?list=true` | `200 application/json` |
|
||
|
||
### Sample Request
|
||
|
||
```
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request LIST \
|
||
https://vault.rocks/v1/identity/group/id
|
||
```
|
||
|
||
### Sample Response
|
||
|
||
```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"
|
||
]
|
||
}
|
||
}
|
||
```
|