From aaba49ca1053fda6e98069ea3451c4051e1efedf Mon Sep 17 00:00:00 2001
From: Sonia Appasamy <sonia@tailscale.com>
Date: Fri, 4 Feb 2022 16:20:46 -0500
Subject: [PATCH] api.md: add docs for device tags and keys endpoints

Signed-off-by: Sonia Appasamy <sonia@tailscale.com>
---
 api.md | 66 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 66 insertions(+)

diff --git a/api.md b/api.md
index 9182fd989..1732df414 100644
--- a/api.md
+++ b/api.md
@@ -15,6 +15,10 @@ Currently based on {some authentication method}. Visit the [admin panel](https:/
     - [POST device routes](#device-routes-post)
   - Authorize machine
     - [POST device authorized](#device-authorized-post)
+  - Tags
+    - [POST device tags](#device-tags-post)
+  - Key
+    - [POST device key](#device-key-post)
 * **[Tailnets](#tailnet)**
   - ACLs
     - [GET tailnet ACL](#tailnet-acl-get)
@@ -268,6 +272,68 @@ curl 'https://api.tailscale.com/api/v2/device/11055/authorized' \
 The response is 2xx on success. The response body is currently an empty JSON
 object.
 
+<a name=device-tags-post></a>
+
+#### `POST /api/v2/device/:deviceID/tags` - update tags on a device
+
+Updates the tags set on a device.
+
+##### Parameters
+
+###### POST Body
+
+`tags` - The new list of tags for the device.
+
+```
+{
+  "tags": ["tag:foo", "tag:bar"]
+}
+```
+
+##### Example
+
+```
+curl 'https://api.tailscale.com/api/v2/device/11055/tags' \
+-u "tskey-yourapikey123:" \
+--data-binary '{"tags": ["tag:foo", "tag:bar"]}'
+```
+
+The response is 2xx on success. The response body is currently an empty JSON
+object.
+
+<a name=device-key-post></a>
+
+#### `POST /api/v2/device/:deviceID/key` - update device key
+
+Allows for updating properties on the device key.
+
+##### Parameters
+
+###### POST Body
+
+`keyExpiryDisabled`
+
+- Provide `true` to disable the device's key expiry. The original key expiry time is still maintained. Upon re-enabling, the key will expire at that original time.
+- Provide `false` to enable the device's key expiry. Sets the key to expire at the original expiry time prior to disabling. The key may already have expired. In that case, the device must be re-authenticated.
+- Empty value will not change the key expiry.
+
+```
+{
+  "keyExpiryDisabled": true
+}
+```
+
+##### Example
+
+```
+curl 'https://api.tailscale.com/api/v2/device/11055/key' \
+-u "tskey-yourapikey123:" \
+--data-binary '{"keyExpiryDisabled": true}'
+```
+
+The response is 2xx on success. The response body is currently an empty JSON
+object.
+
 ## Tailnet 
 A tailnet is the name of your Tailscale network. 
 You can find it in the top left corner of the [Admin Panel](https://login.tailscale.com/admin) beside the Tailscale logo.