-
Notifications
You must be signed in to change notification settings - Fork 1.3k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
publicapi: include device and user invites API documentation (#12168)
This change includes the device and user invites API docs in the new publicapi documentation structure. Updates tailscale/corp#19526 Signed-off-by: Charlotte Brandhorst-Satzkorn <charlotte@tailscale.com>
- Loading branch information
Showing
5 changed files
with
599 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,221 @@ | ||
| # 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/<code>", | ||
|
|
||
| // 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": "" | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| # API | ||
|
|
||
| **[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) | ||
|
|
||
| ## 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/<code>", | ||
| "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": "" | ||
| } | ||
| } | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.