mirror of
https://github.com/hashicorp/vault.git
synced 2026-06-30 21:07:31 -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
213 lines
4.7 KiB
Markdown
213 lines
4.7 KiB
Markdown
---
|
||
layout: "api"
|
||
page_title: "Identity Secret Backend: Entity - HTTP API"
|
||
sidebar_current: "docs-http-secret-identity-entity"
|
||
description: |-
|
||
This is the API documentation for managing entities in the identity store.
|
||
---
|
||
|
||
## Create an Entity
|
||
|
||
This endpoint creates or updates an Entity.
|
||
|
||
| Method | Path | Produces |
|
||
| :------- | :------------------ | :----------------------|
|
||
| `POST` | `/identity/entity` | `200 application/json` |
|
||
|
||
### Parameters
|
||
|
||
- `name` `(string: entity-<UUID>)` – Name of the entity.
|
||
|
||
- `id` `(string: <optional>)` - ID of the entity. If set, updates the
|
||
corresponding existing entity.
|
||
|
||
- `metadata` `(key-value-map: {})` – Metadata to be associated with the
|
||
entity.
|
||
|
||
- `policies` `(list of strings: [])` – Policies to be tied to the entity.
|
||
|
||
### Sample Payload
|
||
|
||
```json
|
||
{
|
||
"metadata": {
|
||
"organization": "hashicorp",
|
||
"team": "vault"
|
||
},
|
||
"policies": ["eng-dev", "infra-dev"]
|
||
}
|
||
```
|
||
|
||
### Sample Request
|
||
|
||
```
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request POST \
|
||
--data @payload.json \
|
||
https://vault.rocks/v1/identity/entity
|
||
```
|
||
|
||
### Sample Response
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"id": "8d6a45e5-572f-8f13-d226-cd0d1ec57297",
|
||
"aliases": null
|
||
}
|
||
}
|
||
```
|
||
|
||
## Read Entity by ID
|
||
|
||
This endpoint queries the entity by its identifier.
|
||
|
||
| Method | Path | Produces |
|
||
| :------- | :--------------------------- | :--------------------- |
|
||
| `GET` | `/identity/entity/id/:id` | `200 application/json` |
|
||
|
||
### Parameters
|
||
|
||
- `id` `(string: <required>)` – Identifier of the entity.
|
||
|
||
### Sample Request
|
||
|
||
```
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
https://vault.rocks/v1/identity/entity/id/8d6a45e5-572f-8f13-d226-cd0d1ec57297
|
||
```
|
||
|
||
### Sample Response
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"bucket_key_hash": "177553e4c58987f4cc5d7e530136c642",
|
||
"creation_time": "2017-07-25T20:29:22.614756844Z",
|
||
"id": "8d6a45e5-572f-8f13-d226-cd0d1ec57297",
|
||
"last_update_time": "2017-07-25T20:29:22.614756844Z",
|
||
"metadata": {
|
||
"organization": "hashicorp",
|
||
"team": "vault"
|
||
},
|
||
"name": "entity-c323de27-2ad2-5ded-dbf3-0c7ef98bc613",
|
||
"aliases": [],
|
||
"policies": [
|
||
"eng-dev",
|
||
"infra-dev"
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
## Update Entity by ID
|
||
|
||
This endpoint is used to update an existing entity.
|
||
|
||
| Method | Path | Produces |
|
||
| :------- | :--------------------------- | :--------------------- |
|
||
| `POST` | `/identity/entity/id/:id` | `200 application/json` |
|
||
|
||
### Parameters
|
||
|
||
- `id` `(string: <required>)` – Identifier of the entity.
|
||
|
||
- `name` `(string: entity-<UUID>)` – Name of the entity.
|
||
|
||
- `metadata` `(key-value-map: {})` – Metadata to be associated with the entity.
|
||
|
||
- `policies` `(list of strings: [])` – Policies to be tied to the entity.
|
||
|
||
|
||
### Sample Payload
|
||
|
||
```json
|
||
{
|
||
"name":"updatedEntityName",
|
||
"metadata": {
|
||
"organization": "hashi",
|
||
"team": "nomad"
|
||
},
|
||
"policies": ["eng-developers", "infra-developers"]
|
||
}
|
||
```
|
||
|
||
### Sample Request
|
||
|
||
```
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request POST \
|
||
--data @payload.json \
|
||
https://vault.rocks/v1/identity/entity/id/8d6a45e5-572f-8f13-d226-cd0d1ec57297
|
||
```
|
||
|
||
### Sample Response
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"id": "8d6a45e5-572f-8f13-d226-cd0d1ec57297",
|
||
"aliases": null
|
||
}
|
||
}
|
||
```
|
||
|
||
## Delete Entity by ID
|
||
|
||
This endpoint deletes an entity and all its associated aliases.
|
||
|
||
| Method | Path | Produces |
|
||
| :--------- | :-------------------------- | :----------------------|
|
||
| `DELETE` | `/identity/entity/id/:id` | `204 (empty body)` |
|
||
|
||
## Parameters
|
||
|
||
- `id` `(string: <required>)` – Identifier of the entity.
|
||
|
||
### Sample Request
|
||
|
||
```
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request DELETE \
|
||
https://vault.rocks/v1/identity/entity/id/8d6a45e5-572f-8f13-d226-cd0d1ec57297
|
||
```
|
||
|
||
## List Entities by ID
|
||
|
||
This endpoint returns a list of available entities by their identifiers.
|
||
|
||
| Method | Path | Produces |
|
||
| :------- | :------------------------------ | :--------------------- |
|
||
| `LIST` | `/identity/entity/id` | `200 application/json` |
|
||
| `GET` | `/identity/entity/id?list=true` | `200 application/json` |
|
||
|
||
### Sample Request
|
||
|
||
```
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request LIST \
|
||
https://vault.rocks/v1/identity/entity/id
|
||
```
|
||
|
||
### Sample Response
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"keys": [
|
||
"02fe5a88-912b-6794-62ed-db873ef86a95",
|
||
"3bf81bc9-44df-8138-57f9-724a9ae36d04",
|
||
"627fba68-98c9-c012-71ba-bfb349585ce1",
|
||
"6c4c805b-b384-3d0e-4d51-44d349887b96",
|
||
"70a72feb-35d1-c775-0813-8efaa8b4b9b5",
|
||
"f1092a67-ce34-48fd-161d-c13a367bc1cd",
|
||
"faedd89a-0d82-c197-c8f9-93a3e6cf0cd0"
|
||
]
|
||
}
|
||
}
|
||
```
|