Transit read-key response documentation omits `latest_version`
- 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
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