From 4d747c18337f69cb322f5fb8ec7d258cba64513a Mon Sep 17 00:00:00 2001
From: Will Norris <will@tailscale.com>
Date: Mon, 18 Mar 2024 12:14:16 -0700
Subject: [PATCH] api.md: document device expiration endpoint

This was originally built for testing node expiration flows, but is also
useful for customers to force device re-auth without actually deleting
the device from the tailnet.

Updates tailscale/corp#18408

Signed-off-by: Will Norris <will@tailscale.com>
---
 api.md | 34 ++++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/api.md b/api.md
index d4cf248e0..b041bc5e1 100644
--- a/api.md
+++ b/api.md
@@ -51,6 +51,7 @@ The Tailscale API does not currently support pagination. All results are returne
 **[Device](#device)**
 - Get a device: [`GET /api/v2/device/{deviceid}`](#get-device)
 - Delete a device: [`DELETE /api/v2/device/{deviceID}`](#delete-device)
+- Expire device key: [`POST /api/v2/device/{deviceID}/expire`](#expire-device-key)
 - **Routes**
   - Get device routes: [`GET /api/v2/device/{deviceID}/routes`](#get-device-routes)
   - Set device routes: [`POST /api/v2/device/{deviceID}/routes`](#set-device-routes)
@@ -412,6 +413,39 @@ HTTP/1.1 501 Not Implemented
 {"message":"cannot delete devices outside of your tailnet"}
 ```
 
+<a href="expire-device-key"></a>
+
+## Expire a device's key
+
+```http
+POST /api/v2/device/{deviceID}/expire
+```
+
+Mark a device's node key as expired.
+This will require the device to re-authenticate in order to connect to the tailnet.
+The device must belong to the requesting user's tailnet.
+
+### Parameters
+
+#### `deviceid` (required in URL path)
+
+The ID of the device.
+
+### Request example
+
+```sh
+curl -X POST 'https://api.tailscale.com/api/v2/device/12345/expire' \
+  -u "tskey-api-xxxxx:"
+```
+
+### Response
+
+If successful, the response should be empty:
+
+```http
+HTTP/1.1 200 OK
+```
+
 <a href="device-routes-get">
 
 ## Get device routes