open-vault/website/source/api/secret/identity/entity.html.md

layout	page_title	sidebar_current	description
api	Identity Secret Backend: Entity - HTTP API	docs-http-secret-identity-entity	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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

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