hashicorp / hashicorp/vault

Transit read-key response documentation omits `latest_version`

Open Beginner friendly
#32,102 0 comments 2 reactions 0 assignees View on GitHub
Dominant language
Go
Stars
36.3k
Forks
4.8k
PR merge metrics
PR metrics pending

Description

### Describe the bug

`GET /v1/transit/keys/:name` returns a `latest_version` field, but it is not documented anywhere:

1. The [Read Key](https://developer.hashicorp.com/vault/api-docs/secret/transit#read-key) page does not mention it, and the sample response omits it.
2. The OpenAPI spec from `/v1/sys/internal/specs/openapi` has no response body definition for this endpoint — the `200` is a bare `"description": "OK"` with no schema reference.
The field is only discoverable by calling the endpoint.

### Steps to reproduce

Against `hashicorp/vault:2.0.4` in dev mode, with `transit` enabled:

$ vault write -f transit/keys/foo
$ curl -sH "X-Vault-Token: $VAULT_TOKEN" "$VAULT_ADDR/v1/transit/keys/foo" \
| jq '.data | {name, latest_version, keys}'
{
"name": "foo",
"latest_version": 1,
"keys": { "1": 1787846981 }
}

$ vault write -f transit/keys/foo/rotate
$ curl -sH "X-Vault-Token: $VAULT_TOKEN" "$VAULT_ADDR/v1/transit/keys/foo" \
| jq '.data | {name, latest_version, keys}'
{
"name": "foo",
"latest_version": 2,
"keys": { "1": 1787846981, "2": 1787846983 }
}

Confirming the spec describes no response fields:

$ curl -sH "X-Vault-Token: $VAULT_TOKEN" "$VAULT_ADDR/v1/sys/internal/specs/openapi" \
| jq '.paths."/transit/keys/{name}".get.responses'
{ "200": { "description": "OK" } }

### Why this matters

We depend on `latest_version` to detect Transit key rotation. Because it is undocumented, a reviewer questioned whether we should rely on it, and suggested deriving the current version from the largest key of the `keys` map instead.

We would prefer the scalar. The `keys` map returns version numbers as JSON object keys, so they must be parsed from strings before comparison, and its value shape appears to vary by key type. A documented scalar is easier to depend on.

### Requests

1. Please document `latest_version` on the Read Key page, including in the sample response.
2. Is `latest_version` guaranteed present for all key types, and always `>= 1` for a key that exists? We currently treat absence as an error and assume no lower bound — `min_encryption_version` is documented in the same response as using `0` as a sentinel for "use the latest version", so we did not want to assume `0` is impossible here without confirmation.
3. Are response schemas for the Transit endpoints planned for the generated OpenAPI spec? That would resolve this class of question generally.
### Vault version

Vault v2.0.4 (c9e9d1d4ddd4b55aae79a8949adffa9e96338720), built 2026-08-03T16:14:36Z

Contributor guide

Open the contributing guide

Research direction

Start with the Read Key page linked in the issue and compare its response example with the live GET /v1/transit/keys/:name response. Inspect /v1/sys/internal/specs/openapi for the corresponding 200 response. Done means the page and sample document latest_version, with its presence and bounds clarified, and the OpenAPI response gap addressed or explicitly scoped.

Written by the indexing model from the issue text.

Assessment

Tech stack
openapi
Domain
api, documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
72/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.