041733d3d1
Add note that API docs have moved to `https://tailscale.com/api` to the top of existing API docs markdown files. Updates https://github.com/tailscale/corp/issues/1301 Signed-off-by: Mario Minardi <mario@tailscale.com>
3.9 KiB
Important
The Tailscale API documentation has moved to https://tailscale.com/api
User invites
A user invite is an active invitation that lets a user join a tailnet with a pre-assigned user role.
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.
Attributes
{
// 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
- Get user invite:
GET /api/v2/user-invites/{userInviteId} - Delete user invite:
DELETE /api/v2/user-invites/{userInviteId} - Resend user invite (by email):
POST /api/v2/user-invites/{userInviteId}/resend
Get user invite
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
curl "https://api.tailscale.com/api/v2/user-invites/29214" \
-u "tskey-api-xxxxx:"
Response
{
"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
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
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
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.
Note: Invite resends are rate limited to one per minute.
Parameters
userInviteId (required in URL path)
The ID of the user invite.
Request example
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.