From 2a9817da397fdfb7941a57bf3e46df45497a67f9 Mon Sep 17 00:00:00 2001
From: phirework <jz@tailscale.com>
Date: Fri, 23 Jun 2023 17:38:20 -0400
Subject: [PATCH] api.md: add info for key description (#8429)

Updates tailscale/corp#7773

Signed-off-by: Jenny Zhang <jz@tailscale.com>
---
 api.md | 17 ++++++++++++++---
 1 file changed, 14 insertions(+), 3 deletions(-)

diff --git a/api.md b/api.md
index 028f71365..095899a47 100644
--- a/api.md
+++ b/api.md
@@ -1222,6 +1222,11 @@ The remaining three methods operate on auth keys and API access tokens.
 
   // expirySeconds (int) is the duration in seconds a new key is valid.
   "expirySeconds": 86400
+
+  // description (string) is an optional short phrase that describes what
+  // this key is used for. It can be a maximum of 50 alphanumeric characters.
+  // Hyphens and underscores are also allowed.
+  "description": "short description of key purpose"
 }
 ```
 
@@ -1308,6 +1313,9 @@ Note the following about required vs. optional values:
   Specifies the duration in seconds until the key should expire.
   Defaults to 90 days if not supplied.
 
+- **`description`:** Optional in `POST` body.
+  A short string specifying the purpose of the key. Can be a maximum of 50 alphanumeric characters. Hyphens and spaces are also allowed.
+
 ### Request example
 
 ``` jsonc
@@ -1325,7 +1333,8 @@ curl "https://api.tailscale.com/api/v2/tailnet/example.com/keys" \
       }
     }
   },
-  "expirySeconds": 86400
+  "expirySeconds": 86400,
+  "description": "dev access"
 }'
 ```
 
@@ -1351,7 +1360,8 @@ It holds the capabilities specified in the request and can no longer be retrieve
         "tags": [ "tag:example" ]
       }
     }
-  }
+  },
+  "description": "dev access"
 }
 ```
 
@@ -1403,7 +1413,8 @@ The response is a JSON object with information about the key supplied.
         ]
       }
     }
-  }
+  },
+  "description": "dev access"
 }
 ```