api.md: document user invite apis

Updates tailscale/corp#18153

Signed-off-by: Sonia Appasamy <[email protected]>

api.md

@@ -97,6 +97,15 @@ The Tailscale API does not currently support pagination. All results are returne
     - Get split DNS: [`GET /api/v2/tailnet/{tailnet}/dns/split-dns`](#get-split-dns)
     - Update split DNS: [`PATCH /api/v2/tailnet/{tailnet}/dns/split-dns`](#update-split-dns)
     - Set split DNS: [`PUT /api/v2/tailnet/{tailnet}/dns/split-dns`](#set-split-dns)
+- [**User invites**](#tailnet-user-invites)
+  - List user invites: [`GET /api/v2/tailnet/{tailnet}/user-invites`](#list-user-invites)
+  - Create user invites: [`POST /api/v2/tailnet/{tailnet}/user-invites`](#create-user-invites)
+
+**[User invites](#user-invites)**
+
+- Get user invite: [`GET /api/v2/user-invites/{userInviteId}`](#get-user-invite)
+- Delete user invite: [`DELETE /api/v2/user-invites/{userInviteId}`](#delete-user-invite)
+- Resend user invite (by email): [`POST /api/v2/user-invites/{userInviteId}/resend`](#resend-user-invite)
 
 # Device
 
@@ -2136,3 +2145,240 @@ The response is a JSON object containing the updated map of split DNS settings.
 ```jsonc
 {}
 ```
+
+## Tailnet user invites
+
+The tailnet user invite methods let you create and list [invites](https://tailscale.com/kb/1371/invite-users).
+
+## List user invites
+
+```http
+GET /api/v2/tailnet/{tailnet}/user-invites
+```
+
+List all user invites that haven't been accepted.
+
+### Parameters
+
+#### `tailnet` (required in URL path)
+
+The tailnet organization name.
+
+### Request example
+
+```sh
+curl -X GET "https://api.tailscale.com/api/v2/tailnet/example.com/user-invites" \
+-u "tskey-api-xxxxx:"
+```
+
+### Response
+
+```json
+[
+  {
+    "id": "29214",
+    "role": "member",
+    "tailnetId": 12345,
+    "inviterId": 34567,
+    "email": "[email protected]",
+    "lastEmailSentAt": "2024-05-09T16:13:16.084568545Z",
+    "inviteUrl": "https://login.tailscale.com/uinv/<code>"
+  },
+  {
+    "id": "29215",
+    "role": "admin",
+    "tailnetId": 12345,
+    "inviterId": 34567,
+    "inviteUrl": "https://login.tailscale.com/uinv/<code>"
+  }
+]
+```
+
+## Create user invites
+
+```http
+POST /api/v2/tailnet/{tailnet}/user-invites
+```
+
+Create new user invites to join the tailnet.
+
+### Parameters
+
+#### `tailnet` (required in URL path)
+
+The tailnet organization name.
+
+#### List of invite requests (required in `POST` body)
+
+Each invite request is an object with the following optional fields:
+
+- **`role`:** (Optional) Specify a [user role](https://tailscale.com/kb/1138/user-roles) to assign the invited user. Defaults to the `"member"` role. Valid options are:
+  - `"member"`: Assign the Member role.
+  - `"admin"`: Assign the Admin role.
+  - `"it-admin"`: Assign the IT admin role.
+  - `"network-admin"`: Assign the Network admin role.
+  - `"billing-admin"`: Assign the Billing admin role.
+  - `"auditor"`: Assign the Auditor role.
+- **`email`:** (Optional) Specify the email to send the created invite. If not set, the endpoint generates and returns an invite URL (but doesn't send it out).
+
+### Request example
+
+```sh
+curl -X POST "https://api.tailscale.com/api/v2/tailnet/example.com/user-invites" \
+-u "tskey-api-xxxxx:" \
+-H "Content-Type: application/json" \
+--data-binary '[{"role": "admin", "email":"[email protected]"}]'
+```
+
+### Response
+
+```jsonc
+[
+  {
+    "id": "29214",
+    "role": "admin",
+    "tailnetId": 12345,
+    "inviterId": 34567,
+    "email": "[email protected]",
+    "lastEmailSentAt": "2024-05-09T16:23:26.91778771Z",
+    "inviteUrl": "https://login.tailscale.com/uinv/<code>"
+  }
+]
+```
+
+# User invites
+
+A user invite is an active invitation that lets a user join a tailnet with a pre-assigned [user role](https://tailscale.com/kb/1138/user-roles).
+
+Each user invite has a unique ID that is used to identify the invite in API calls.
+You can find all user invite IDs for a particular tailnet by [listing user invites](#list-user-invites).
+
+### Attributes
+
+```jsonc
+{
+  // id (string) is the unique identifier for the invite.
+  // Supply this value wherever {userInviteId} is indicated in the endpoint.
+  "id": "12346",
+
+  // role is the tailnet user role to assign to the invited user upon accepting
+  // the invite. Value options are "member", "admin", "it-admin", "network-admin",
+  // "billing-admin", and "auditor".
+  "role": "admin",
+
+  // tailnetId is the ID of the tailnet to which the user was invited.
+  "tailnetId": 59954,
+
+  // inviterId is the ID of the user who created the invite.
+  "inviterId": 22012,
+
+  // email is the email to which the invite was sent.
+  // If empty, the invite was not emailed to anyone, but the inviteUrl can be
+  // shared manually.
+  "email": "[email protected]",
+
+  // lastEmailSentAt is the last time the invite was attempted to be sent to
+  // Email. Only ever set if `email` is not empty.
+  "lastEmailSentAt": "2024-04-03T21:38:49.333829261Z",
+
+  // inviteUrl is included when `email` is not part of the tailnet's domain,
+  // or when `email` is empty. It is the link to accept the invite.
+  //
+  // When included, anyone with this link can accept the invite.
+  // It is not restricted to the person to which the invite was emailed.
+  //
+  // When `email` is part of the tailnet's domain (has the same @domain.com
+  // suffix as the tailnet), the user can join the tailnet automatically by
+  // logging in with their domain email at https://login.tailscale.com/start.
+  // They'll be assigned the specified `role` upon signing in for the first
+  // time.
+  "inviteUrl": "https://login.tailscale.com/admin/invite/<code>"
+}
+```
+
+## Get user invite
+
+```http
+GET /api/v2/user-invites/{userInviteId}
+```
+
+Retrieve the specified user invite.
+
+### Parameters
+
+#### `userInviteId` (required in URL path)
+
+The ID of the user invite.
+
+### Request example
+
+```sh
+curl "https://api.tailscale.com/api/v2/user-invites/29214" \
+  -u "tskey-api-xxxxx:"
+```
+
+### Response
+
+```jsonc
+{
+  "id": "29214",
+  "role": "admin",
+  "tailnetId": 12345,
+  "inviterId": 34567,
+  "email": "[email protected]",
+  "lastEmailSentAt": "2024-05-09T16:23:26.91778771Z",
+  "inviteUrl": "https://login.tailscale.com/uinv/<code>"
+}
+```
+
+## Delete user invite
+
+```http
+DELETE /api/v2/user-invites/{userInviteId}
+```
+
+Delete the specified user invite.
+
+### Parameters
+
+#### `userInviteId` (required in URL path)
+
+The ID of the user invite.
+
+### Request example
+
+```sh
+curl -X DELETE "https://api.tailscale.com/api/v2/user-invites/29214" \
+  -u "tskey-api-xxxxx:"
+```
+
+### Response
+
+The response is 2xx on success. The response body is an empty JSON object.
+
+## Resend user invite
+
+```http
+POST /api/v2/user-invites/{userInviteId}/resend
+```
+
+Resend the specified user invite by email. You can only use this if the specified invite was originally created with an email specified. Refer to [creating user invites for a tailnet](#create-user-invites).
+
+Note: Invite resends are rate limited to one per minute.
+
+### Parameters
+
+#### `userInviteId` (required in URL path)
+
+The ID of the user invite.
+
+### Request example
+
+```sh
+curl -X POST "https://api.tailscale.com/api/v2/user-invites/29214/resend" \
+  -u "tskey-api-xxxxx:"
+```
+
+### Response
+
+The response is 2xx on success. The response body is an empty JSON object.