From a101ebf75507a0913d2ed324bf0efcec982b27cd Mon Sep 17 00:00:00 2001
From: Peter Amstutz <peter.amstutz@curii.com>
Date: Fri, 25 Sep 2020 11:46:36 -0400
Subject: [PATCH] 16825: Document deleting token at the CLI

Arvados-DCO-1.1-Signed-off-by: Peter Amstutz <peter.amstutz@curii.com>
---
 .../user-management-cli.html.textile.liquid   | 46 +++++++++++++++++++
 1 file changed, 46 insertions(+)

diff --git a/doc/admin/user-management-cli.html.textile.liquid b/doc/admin/user-management-cli.html.textile.liquid
index 6892176604..8cebf02cdc 100644
--- a/doc/admin/user-management-cli.html.textile.liquid
+++ b/doc/admin/user-management-cli.html.textile.liquid
@@ -85,6 +85,52 @@ To get the token string, combine the values of @uuid@ and @api_token@ in the for
 ARVADOS_API_TOKEN=v2/zzzzz-gj3su-yyyyyyyyyyyyyyy/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 </pre>
 
+h3(#delete-token). Delete a token
+
+If you need to revoke a token, for example the token is leaked to an unauthorized party, you can delete the token at the command line.
+
+1. First, determine the token UUID.  If it is a "v2" format token (starts with "v2/") then the token UUID is middle section between the two slashes.   For example:
+
+<pre>
+v2/zzzzz-gj3su-yyyyyyyyyyyyyyy/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+</pre>
+
+the UUID is "zzzzz-gj3su-yyyyyyyyyyyyyyy" and you can skip to the next step.
+
+If you have a "bare" token (only the secret part) then, as an admin, you need to query the token to get the uuid:
+
+<pre>
+$ ARVADOS_API_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx arv api_client_authorization current
+{
+ "href":"/api_client_authorizations/x33hz-gj3su-fk8nbj4byptz6ma",
+ "kind":"arvados#apiClientAuthorization",
+ "etag":"77wktnitqeelbgb4riv84zi2q",
+ "uuid":"zzzzz-gj3su-yyyyyyyyyyyyyyy",
+ "owner_uuid":"zzzzz-tpzed-j8w1ymjsn4vf4v4",
+ "created_at":"2020-09-25T15:19:48.606984000Z",
+ "modified_by_client_uuid":null,
+ "modified_by_user_uuid":null,
+ "modified_at":null,
+ "user_id":3,
+ "api_client_id":1,
+ "api_token":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+ "created_by_ip_address":null,
+ "default_owner_uuid":null,
+ "expires_at":null,
+ "last_used_at":null,
+ "last_used_by_ip_address":null,
+ "scopes":[
+  "all"
+ ]
+}
+</pre>
+
+2. Now use the token to delete itself:
+
+<pre>
+$ ARVADOS_API_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx arv api_client_authorization delete --uuid zzzzz-gj3su-yyyyyyyyyyyyyyy
+</pre>
+
 h2. Adding Permissions
 
 h3. VM login
-- 
2.30.2