From 89947606b2f47ef5926e95dbd59481f819ab65a2 Mon Sep 17 00:00:00 2001 From: Sonia Appasamy Date: Wed, 15 May 2024 13:27:18 -0400 Subject: [PATCH] api.md: document device invite apis Updates tailscale/corp#18153 Signed-off-by: Sonia Appasamy --- api.md | 334 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 333 insertions(+), 1 deletion(-) diff --git a/api.md b/api.md index 7aab55d88..7fe05624b 100644 --- a/api.md +++ b/api.md @@ -68,6 +68,9 @@ The Tailscale API does not currently support pagination. All results are returne - Get device posture attributes: [`GET /api/v2/device/{deviceID}/attributes`](#get-device-posture-attributes) - Set custom device posture attributes: [`POST /api/v2/device/{deviceID}/attributes/{attributeKey}`](#set-device-posture-attributes) - Delete custom device posture attributes: [`DELETE /api/v2/device/{deviceID}/attributes/{attributeKey}`](#delete-custom-device-posture-attributes) +- [**Device invites**](#invites-to-a-device) + - List device invites: [`GET /api/v2/device/{deviceID}/device-invites`](#list-device-invites) + - Create device invites: [`POST /api/v2/device/{deviceID}/device-invites`](#create-device-invites) **[Tailnet](#tailnet)** @@ -107,6 +110,13 @@ The Tailscale API does not currently support pagination. All results are returne - 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 invites](#device-invites)** + +- Get device invite: [`GET /api/v2/device-invites/{deviceInviteId}`](#get-device-invite) +- Delete device invite: [`DELETE /api/v2/device-invites/{deviceInviteId}`](#delete-device-invite) +- Resend device invite (by email): [`POST /api/v2/device-invites/{deviceInviteId}/resend`](#resend-device-invite) +- Accept device invite [`POST /api/v2/device-invites/-/accept`](#accept-device-invite) + # Device A Tailscale device (sometimes referred to as _node_ or _machine_), is any computer or mobile device that joins a tailnet. @@ -868,6 +878,115 @@ curl -X DELETE "https://api.tailscale.com/api/v2/device/11055/attributes/custom: The response is 2xx on success. The response body is currently an empty JSON object. +## Invites to a device + +The device sharing invite methods let you create and list [invites to share a device](https://tailscale.com/kb/1084/sharing). + +## List device invites + +```http +GET /api/v2/device/{deviceID}/device-invites +``` + +List all share invites for a device. + +### Parameters + +#### `deviceID` (required in URL path) + +The ID of the device. + +### Request example + +```sh +curl -X GET "https://api.tailscale.com/api/v2/device/11055/device-invites" \ +-u "tskey-api-xxxxx:" +``` + +### Response + +```jsonc +[ + { + "id": "12345", + "created": "2024-05-08T20:19:51.777861756Z", + "tailnetId": 59954, + "deviceId": 11055, + "sharerId": 22011, + "allowExitNode": true, + "email": "user@example.com", + "lastEmailSentAt": "2024-05-08T20:19:51.777861756Z", + "inviteUrl": "https://login.tailscale.com/admin/invite/", + "accepted": false + }, + { + "id": "12346", + "created": "2024-04-03T21:38:49.333829261Z", + "tailnetId": 59954, + "deviceId": 11055, + "sharerId": 22012, + "inviteUrl": "https://login.tailscale.com/admin/invite/", + "accepted": true, + "acceptedBy": { + "id": 33223, + "loginName": "someone@example.com", + "profilePicUrl": "" + } + } +] +``` + +## Create device invites + +```http +POST /api/v2/device/{deviceID}/device-invites +``` + +Create new share invites for a device. + +### Parameters + +#### `deviceID` (required in URL path) + +The ID of the device. + +#### List of invite requests (required in `POST` body) + +Each invite request is an object with the following optional fields: + +- **`multiUse`:** (Optional) Specify whether the invite can be accepted more than once. When set to `true`, it results in an invite that can be accepted up to 1,000 times. +- **`allowExitNode`:** (Optional) Specify whether the invited user can use the device as an exit node when it advertises as one. +- **`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/device/11055/device-invites" \ +-u "tskey-api-xxxxx:" \ +-H "Content-Type: application/json" \ +--data-binary '[{"multiUse": true, "allowExitNode": true, "email":"user@example.com"}]' +``` + +### Response + +```jsonc +[ + { + "id": "12347", + "created": "2024-05-08T20:29:45.842358533Z", + "tailnetId": 59954, + "deviceId": 11055, + "sharerId": 22012, + "multiUse": true, + "allowExitNode": true, + "email": "user@example.com", + "lastEmailSentAt": "2024-05-08T20:29:45.842358533Z", + "inviteUrl": "https://login.tailscale.com/admin/invite/", + "accepted": false + } +] +``` + # Tailnet A tailnet is your private network, composed of all the devices on it and their configuration. @@ -2173,7 +2292,7 @@ curl -X GET "https://api.tailscale.com/api/v2/tailnet/example.com/user-invites" ### Response -```json +```jsonc [ { "id": "29214", @@ -2382,3 +2501,216 @@ curl -X POST "https://api.tailscale.com/api/v2/user-invites/29214/resend" \ ### Response The response is 2xx on success. The response body is an empty JSON object. + +# Device invites + +A device invite is an invitation that shares a device with an external user (a user not in the device's tailnet). + +Each device invite has a unique ID that is used to identify the invite in API calls. +You can find all device invite IDs for a particular device by [listing all device invites for a device](#list-device-invites). + +### Attributes + +```jsonc +{ + // id (strings) is the unique identifier for the invite. + // Supply this value wherever {deviceInviteId} is indicated in the endpoint. + "id": "12346", + + // created is the creation time of the invite. + "created": "2024-04-03T21:38:49.333829261Z", + + // tailnetId is the ID of the tailnet to which the shared device belongs. + "tailnetId": 59954, + + // deviceId is the ID of the device being shared. + "deviceId": 11055, + + // sharerId is the ID of the user who created the share invite. + "sharerId": 22012, + + // multiUse specifies whether this device invite can be accepted more than + // once. + "multiUse": false, + + // allowExitNode specifies whether the invited user is able to use the + // device as an exit node when the device is advertising as one. + "allowExitNode": true, + + // 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": "user@example.com", + + // 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 the link to accept the invite. + // Anyone with this link can accept the invite. + // It is not restricted to the person to which the invite was emailed. + "inviteUrl": "https://login.tailscale.com/admin/invite/", + + // accepted is true when share invite has been accepted. + "accepted": true, + + // acceptedBy is set when the invite has been accepted. + // It holds information about the user who accepted the share invite. + "acceptedBy": { + // id is the ID of the user who accepted the share invite. + "id": 33223, + + // loginName is the login name of the user who accepted the share invite. + "loginName": "someone@example.com", + + // profilePicUrl is optionally the profile pic URL for the user who accepted + // the share invite. + "profilePicUrl": "" + } +} +``` + +## Get device invite + +```http +GET /api/v2/device-invites/{deviceInviteId} +``` + +Retrieve the specified device invite. + +### Parameters + +#### `deviceInviteId` (required in URL path) + +The ID of the device share invite. + +### Request example + +```sh +curl "https://api.tailscale.com/api/v2/device-invites/12346" \ + -u "tskey-api-xxxxx:" +``` + +### Response + +```jsonc +{ + "id": "12346", + "created": "2024-04-03T21:38:49.333829261Z", + "tailnetId": 59954, + "deviceId": 11055, + "sharerId": 22012, + "multiUse": true, + "allowExitNode": true, + "email": "user@example.com", + "lastEmailSentAt": "2024-04-03T21:38:49.333829261Z", + "inviteUrl": "https://login.tailscale.com/admin/invite/", + "accepted": false +} +``` + +## Delete device invite + +```http +DELETE /api/v2/device-invites/{deviceInviteId} +``` + +Delete the specified device invite. + +### Parameters + +#### `deviceInviteId` (required in URL path) + +The ID of the device share invite. + +### Request example + +```sh +curl -X DELETE "https://api.tailscale.com/api/v2/device-invites/12346" \ + -u "tskey-api-xxxxx:" +``` + +### Response + +The response is 2xx on success. The response body is an empty JSON object. + +## Resend device invite + +```http +POST /api/v2/device-invites/{deviceInviteId}/resend +``` + +Resend the specified device invite by email. You can only use this if the specified invite was originally created with an email specified. Refer to [creating device invites for a device](#create-device-invites). + +Note: Invite resends are rate limited to one per minute. + +### Parameters + +#### `deviceInviteId` (required in URL path) + +The ID of the device share invite. + +### Request example + +```sh +curl -X POST "https://api.tailscale.com/api/v2/device-invites/12346/resend" \ + -u "tskey-api-xxxxx:" +``` + +### Response + +The response is 2xx on success. The response body is an empty JSON object. + +## Accept device invite + +```http +POST /api/v2/device-invites/-/accept +``` + +Resend the specified device invite by email. This can only be used if the specified invite was originally created with an email specified. +See [creating device invites for a device](#create-device-invites). + +Note that invite resends are rate limited to once per minute. + +### Parameters + +#### `invite` (required in `POST` body) + +The URL of the invite (in the form "https://login.tailscale.com/admin/invite/{code}") or the "{code}" component of the URL. + +### Request example + +```sh +curl -X POST "https://api.tailscale.com/api/v2/device-invites/-/accept" \ + -u "tskey-api-xxxxx:" \ + -H "Content-Type: application/json" \ + --data-binary '[{"invite": "https://login.tailscale.com/admin/invite/xxxxxx"}]' +``` + +### Response + +```jsonc +{ + "device": { + "id": "11055", + "os": "iOS", + "name": "my-phone", + "fqdn": "my-phone.something.ts.net", + "ipv4": "100.x.y.z", + "ipv6": "fd7a:115c:x::y:z", + "includeExitNode": false + }, + "sharer": { + "id": "22012", + "displayName": "Some User", + "loginName": "someuser@example.com", + "profilePicURL": "" + }, + "acceptedBy": { + "id": "33233", + "displayName": "Another User", + "loginName": "anotheruser@exmaple2.com", + "profilePicURL": "" + } +} +```