From 05bf6592b17a1b231dcf04d72b7fa57961ea9d2a Mon Sep 17 00:00:00 2001
From: Samuel Arogbonlo <47984109+samuelarogbonlo@users.noreply.github.com>
Date: Tue, 15 Jul 2025 03:50:15 +0300
Subject: [PATCH] docs: improve token renewal documentation consistency
 (#29693)

* docs: improve token renewal documentation consistency

* Update website/content/docs/commands/token/renew.mdx

Co-authored-by: Sarah Chavis <62406755+schavis@users.noreply.github.com>

* Update website/content/docs/commands/token/renew.mdx

Co-authored-by: Sarah Chavis <62406755+schavis@users.noreply.github.com>

* Update website/content/docs/commands/token/renew.mdx

Co-authored-by: Sarah Chavis <62406755+schavis@users.noreply.github.com>

---------

Co-authored-by: Sarah Chavis <62406755+schavis@users.noreply.github.com>
---
 website/content/docs/commands/token/renew.mdx | 49 +++++++++++++++++--
 1 file changed, 44 insertions(+), 5 deletions(-)

diff --git a/website/content/docs/commands/token/renew.mdx b/website/content/docs/commands/token/renew.mdx
index 38934e6920..233f67c8a9 100644
--- a/website/content/docs/commands/token/renew.mdx
+++ b/website/content/docs/commands/token/renew.mdx
@@ -17,10 +17,44 @@ revoked, or if the token has already reached its maximum TTL.
 
 ## Examples
 
-Renew a token (this uses the `/auth/token/renew` endpoint and permission):
+Create a token first:
 
 ```shell-session
-$ vault token renew 96ddf4bc-d217-f3ba-f9bd-017055595017
+$ vault token create
+Key                Value
+---                -----
+token              hvs.CAESIJk8P_ieg60yf9c92rl0S5j1mdMh7docAoHVS2q7UQ8bGh4KHGh2cy5uQ3dNQUhvbnFhTWl5cVJpMGxpVDhMZWU
+token_accessor     ntL634hzE0CtQnyCIqkxSa82
+token_duration     768h
+token_renewable    true
+token_policies     [default]
+```
+
+Renew a token using the token value and the `/auth/token/renew` endpoint:
+
+```shell-session
+$ vault token renew hvs.CAESIJk8P_ieg6Oyf9c92rl0S5j1mdMh7docAoHVS2q7UQ8bGh4KHGh2cy5uQ3dNQUhvbnFhTWl5cVJpMGxpVDhMZWU
+Key                Value
+---                -----
+token              n/a
+token_accessor     ntL634hzE0CtQnyCIqkxSa82
+token_duration     768h
+token_renewable    true
+token_policies     [default]
+```
+
+Alternatively, renew a token using its accessor value. Renewing with the
+ accessor vault is is useful when you do not have the actual token:
+
+```shell-session
+$ vault token renew -accessor ntL634hzE0CtQnyCIqkxSa82
+Key                Value
+---                -----
+token              n/a
+token_accessor     ntL634hzE0CtQnyCIqkxSa82
+token_duration     768h
+token_renewable    true
+token_policies     [default]
 ```
 
 Renew the currently authenticated token (this uses the `/auth/token/renew-self`
@@ -33,15 +67,20 @@ $ vault token renew
 Renew a token requesting a specific increment value:
 
 ```shell-session
-$ vault token renew -increment=30m 96ddf4bc-d217-f3ba-f9bd-017055595017
+$ vault token renew -increment=30m hvs.CAESIJk8P_ieg6Oyf9c92rl0S5j1mdMh7docAoHVS2q7UQ8bGh4KHGh2cy5uQ3dNQUhvbnFhTWl5cVJpMGxpVDhMZWU
 ```
 
 Fail if the requested TTL increment cannot be fully fulfilled:
 
 ```shell-session
-$ vault token renew -increment=30m 96ddf4bc-d217-f3ba-f9bd-017055595017 --fail-if-not-fulfilled || vault login
+$ vault token renew -increment=30m hvs.CAESIJk8P_ieg6Oyf9c92rl0S5j1mdMh7docAoHVS2q7UQ8bGh4KHGh2cy5uQ3dNQUhvbnFhTWl5cVJpMGxpVDhMZWU --fail-if-not-fulfilled || vault login
 ```
 
+You can renew tokens using the token itself or the associated accessor.
+The `token_accessor` parameter lets you perform limited operations (like
+renewal) without requiring sensitive data so you can manage  tokens
+without handling the secret token itself.
+
 ## Usage
 
 The following flags are available in addition to the [standard set of
@@ -65,4 +104,4 @@ token. When this option is selected, the output will NOT include the token.
 
 - `--fail-if-not-fulfilled` - Fail if the requested TTL increment cannot be
 fully fulfilled. Vault allows command chaining and token renewal request
-completion with capped duration even if renew request fails.
\ No newline at end of file
+completion with capped duration even if renew request fails.