Identity secrets engine - TPM group (API)

A TPM group organizes TPM records into logical collections for authorization purposes. Groups have a UUID-based ID, a human-friendly name, optional metadata, and a list of member TPM IDs.

Key characteristics of TPM groups:

• The ID is a randomly generated UUID (unlike TPM records, whose ID is derived from the EK public key).
• If a name is not provided on creation, Vault generates a default name in the format tpmgroup_<random-hex>.
• TPM group names must be unique within a namespace. Attempting to create a second group with a duplicate name returns an error.
• All TPM IDs listed in member_tpm_ids must already exist in the same namespace. Requests for an unknown ID return an error.
• Supplying member_tpm_ids on an update replaces the full member list rather than merging.
• Supplying metadata on an update replaces the full metadata map rather than merging.

Create a TPM group

Create a new TPM group from existing TPM IDs in the same namespace.

Parameters

• name (string: "tpmgroup-<random-hex>") – A human-friendly name for the TPM group. Must be unique within the namespace.

• id (string: <optional>) – ID of an existing TPM group to update. If set, the request updates that group rather than creating a new one.

• metadata (key-value-map: {}) – Metadata to be associated with the group. In CLI commands, you can repeat the metadata parameter multiple times and Vault will merge them together to create a single update string.

• member_tpm_ids (comma-separated string list: []) – List of TPM record IDs to assign as members of the group. Every ID must reference an existing TPM record in the current namespace.

Sample payload

{
  "name": "datacenter-east-tpms",
  "metadata": {
    "environment": "production",
    "region": "us-east-1"
  },
  "member_tpm_ids": [
    "sha256-a3f1c2d4e5b6...",
    "sha256-7d8e9f0a1b2c..."
  ]
}

Sample request

$ curl \
    --header "X-Vault-Token: ${VAULT_TOKEN}" \
    --request POST \
    --data @payload.json \
    ${VAULT_ADDR}/v1/identity/tpmgroup

Sample response

{
  "data": {
    "id": "",
    "name": "datacenter-east-tpms"
  }
}

Read TPM group by ID

Query a TPM group by its identifier.

Parameters

• id (string: <required>) – Identifier of the TPM group.

Sample request

$ curl \
    --header "X-Vault-Token: ${VAULT_TOKEN}" \
    ${VAULT_ADDR}/v1/identity/tpmgroup/id/00000000-0000-0000-0000-000000000000

Sample response

{
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "member_tpm_ids": [
      "sha256-a3f1c2d4e5b6...",
      "sha256-7d8e9f0a1b2c..."
    ],
    "metadata": {
      "environment": "production",
      "region": "us-east-1"
    },
    "name": "datacenter-east-tpms"
  }
}

Update TPM group by ID

Update an existing TPM group by its identifier.

Parameters

• id (string: <required>) – Identifier of the TPM group.

• name (string: <optional>) – Updated name for the group. Must be unique within the namespace.

• metadata (key-value-map: {}) – Updated metadata. Replaces existing metadata entirely.

• member_tpm_ids (comma-separated string list: []) – Updated list of member TPM IDs. Replaces the existing member list entirely. Every ID must reference an existing TPM record in the current namespace.

Sample payload

{
  "metadata": {
    "environment": "staging"
  },
  "member_tpm_ids": [
    "sha256-a3f1c2d4e5b6..."
  ]
}

Sample request

$ curl \
    --header "X-Vault-Token: ${VAULT_TOKEN}" \
    --request POST \
    --data @payload.json \
    ${VAULT_ADDR}/v1/identity/tpmgroup/id/00000000-0000-0000-0000-000000000000

Sample response

{
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "name": "datacenter-east-tpms"
  }
}

Delete TPM group by ID

Deletes a TPM group by its identifier. Deleting a group that does not exist is idempotent and returns successfully as a no-op.

Parameters

• id (string: <required>) – Identifier of the TPM group.

Sample request

$ curl \
    --header "X-Vault-Token: ${VAULT_TOKEN}" \
    --request DELETE \
    ${VAULT_ADDR}/v1/identity/tpmgroup/id/00000000-0000-0000-0000-000000000000

List TPM groups by ID

Fetch a list of all TPM group identifiers in the current namespace.

Sample request

$ curl \
    --header "X-Vault-Token: ${VAULT_TOKEN}" \
    --request LIST \
    ${VAULT_ADDR}/v1/identity/tpmgroup/id

Sample response

{
  "data": {
    "keys": [
      "00000000-0000-0000-0000-000000000000",
      "11111111-1111-1111-1111-111111111111"
    ]
  }
}

Read TPM group by name

Fetch TPM group details by name.

Parameters

• name (string: <required>) – Name of the TPM group.

Sample request

$ curl \
    --header "X-Vault-Token: ${VAULT_TOKEN}" \
    ${VAULT_ADDR}/v1/identity/tpmgroup/name/datacenter-east-tpms

Sample response

{
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "member_tpm_ids": [
      "sha256-a3f1c2d4e5b6..."
    ],
    "metadata": {
      "environment": "staging"
    },
    "name": "datacenter-east-tpms"
  }
}

Update TPM group by name

Updates an existing TPM group by its name. You cannot use the update endpoint to create new groups.

Providing member_tpm_ids replaces the existing member list entirely. Providing metadata replaces the existing metadata map entirely.

Parameters

• name (string: <required>) – Name of the TPM group to update.

• metadata (key-value-map: {}) – Updated metadata. Replaces existing metadata entirely.

• member_tpm_ids (comma-separated string list: []) – Updated list of member TPM IDs. Replaces the existing member list entirely. Every ID must reference an existing TPM record in the current namespace.

Sample payload

{
  "metadata": {
    "environment": "production",
    "version": "2"
  },
  "member_tpm_ids": [
    "sha256-a3f1c2d4e5b6...",
    "sha256-7d8e9f0a1b2c..."
  ]
}

Sample request

$ curl \
    --header "X-Vault-Token: ${VAULT_TOKEN}" \
    --request POST \
    --data @payload.json \
    ${VAULT_ADDR}/v1/identity/tpmgroup/name/datacenter-east-tpms

Sample response

{
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "name": "datacenter-east-tpms"
  }
}

Delete TPM group by name

Deletes a TPM group by its identifier. Deleting a group that does not exist is idempotent and returns successfully as a no-op.

Parameters

• name (string: <required>) – Name of the TPM group.

Sample request

$ curl \
    --header "X-Vault-Token: ${VAULT_TOKEN}" \
    --request DELETE \
    ${VAULT_ADDR}/v1/identity/tpmgroup/name/datacenter-east-tpms

List TPM groups by name

Fetch a list of all TPM group names in the current namespace.

Sample request

$ curl \
    --header "X-Vault-Token: ${VAULT_TOKEN}" \
    --request LIST \
    ${VAULT_ADDR}/v1/identity/tpmgroup/name

Sample response

{
  "data": {
    "keys": [
      "datacenter-east-tpms",
      "datacenter-west-tpms"
    ]
  }
}