mirror of
https://github.com/tailscale/tailscale.git
synced 2024-12-01 14:05:39 +00:00
api.md: document user invite apis
Updates tailscale/corp#18153 Signed-off-by: Sonia Appasamy <sonia@tailscale.com>
This commit is contained in:
Sonia Appasamy
Sonia Appasamy
parent
e3dec086e6
commit
b094e8c925
246
api.md
246
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)
|
- 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)
|
- 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)
|
- 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
|
# Device
|
||||||
|
|
||||||
@ -2136,3 +2145,240 @@ The response is a JSON object containing the updated map of split DNS settings.
|
|||||||
```jsonc
|
```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": "user@example.com",
|
||||||
|
"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":"user@example.com"}]'
|
||||||
|
```
|
||||||
|
|
||||||
|
### 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>"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
```
|
||||||
|
|
||||||
|
# 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>"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## 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
Block a user