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>main
Charlotte Brandhorst-Satzkorn
2 years ago
committed by
GitHub
parent
adb7a86559
commit
c56e0c4934
@ -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": "" |
||||
} |
||||
} |
||||
``` |
||||
@ -0,0 +1,144 @@ |
||||
# 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": "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 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>" |
||||
} |
||||
``` |
||||
|
||||
# API |
||||
|
||||
**[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) |
||||
|
||||
## 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": "user@example.com", |
||||
"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. |
||||
Loading…
Reference in new issue