mirror of https://github.com/tailscale/tailscale/
{api.md,publicapi}: remove old API docs (#13468)
Now that we have our API docs hosted at https://tailscale.com/api we can remove the previous (and now outdated) markdown based docs. The top level api.md has been left with the only content being the redirect to the new docs. Updates #cleanup Signed-off-by: Mario Minardi <mario@tailscale.com>pull/13481/head
Mario Minardi
2 months ago
committed by
GitHub
parent
afec2d41b4
commit
124ff3b034
@ -1,224 +0,0 @@
|
||||
> [!IMPORTANT]
|
||||
> The Tailscale API documentation has moved to https://tailscale.com/api
|
||||
|
||||
# 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": ""
|
||||
}
|
||||
}
|
||||
```
|
||||
@ -1,121 +0,0 @@
|
||||
> [!IMPORTANT]
|
||||
> The Tailscale API documentation has moved to https://tailscale.com/api
|
||||
|
||||
# Tailscale API
|
||||
|
||||
The Tailscale API is a (mostly) RESTful API. Typically, both `POST` bodies and responses are JSON-encoded.
|
||||
|
||||
## Base URL
|
||||
|
||||
The base URL for the Tailscale API is `https://api.tailscale.com/api/v2/`.
|
||||
|
||||
Examples in this document may abbreviate this to `/api/v2/`.
|
||||
|
||||
## Authentication
|
||||
|
||||
Requests to the Tailscale API are authenticated with an API access token (sometimes called an API key).
|
||||
Access tokens can be supplied as the username portion of HTTP Basic authentication (leave the password blank) or as an OAuth Bearer token:
|
||||
|
||||
```sh
|
||||
# passing token with basic auth
|
||||
curl -u "tskey-api-xxxxx:" https://api.tailscale.com/api/v2/...
|
||||
|
||||
# passing token as bearer token
|
||||
curl -H "Authorization: Bearer tskey-api-xxxxx" https://api.tailscale.com/api/v2/...
|
||||
```
|
||||
|
||||
Access tokens for individual users can be created and managed from the [**Keys**](https://login.tailscale.com/admin/settings/keys) page of the admin console.
|
||||
These tokens will have the same permissions as the owning user, and can be set to expire in 1 to 90 days.
|
||||
Access tokens are identifiable by the prefix `tskey-api-`.
|
||||
|
||||
Alternatively, an OAuth client can be used to create short-lived access tokens with scoped permission.
|
||||
OAuth clients don't expire, and can therefore be used to provide ongoing access to the API, creating access tokens as needed.
|
||||
OAuth clients and the access tokens they create are not tied to an individual Tailscale user.
|
||||
OAuth client secrets are identifiable by the prefix `tskey-client-`.
|
||||
Learn more about [OAuth clients](https://tailscale.com/kb/1215/).
|
||||
|
||||
## Errors
|
||||
|
||||
The Tailscale API returns status codes consistent with [standard HTTP conventions](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status).
|
||||
In addition to the status code, errors may include additional information in the response body:
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"message": "additional error information"
|
||||
}
|
||||
```
|
||||
|
||||
## Pagination
|
||||
|
||||
The Tailscale API does not currently support pagination. All results are returned at once.
|
||||
|
||||
# APIs
|
||||
|
||||
**[Device](./device.md#device)**
|
||||
|
||||
- Get a device: [`GET /api/v2/device/{deviceid}`](./device.md#get-device)
|
||||
- Delete a device: [`DELETE /api/v2/device/{deviceID}`](./device.md#delete-device)
|
||||
- Expire device key: [`POST /api/v2/device/{deviceID}/expire`](./device.md#expire-device-key)
|
||||
- [**Routes**](./device.md#routes)
|
||||
- Get device routes: [`GET /api/v2/device/{deviceID}/routes`](./device.md#get-device-routes)
|
||||
- Set device routes: [`POST /api/v2/device/{deviceID}/routes`](./device.md#set-device-routes)
|
||||
- [**Authorize**](./device.md#authorize)
|
||||
- Authorize a device: [`POST /api/v2/device/{deviceID}/authorized`](./device.md#authorize-device)
|
||||
- [**Tags**](./device.md#tags)
|
||||
- Update tags: [`POST /api/v2/device/{deviceID}/tags`](./device.md#update-device-tags)
|
||||
- [**Keys**](./device.md#keys)
|
||||
- Update device key: [`POST /api/v2/device/{deviceID}/key`](./device.md#update-device-key)
|
||||
- [**IP Addresses**](./device.md#ip-addresses)
|
||||
- Set device IPv4 address: [`POST /api/v2/device/{deviceID}/ip`](./device.md#set-device-ipv4-address)
|
||||
- [**Device posture attributes**](./device.md#device-posture-attributes)
|
||||
- Get device posture attributes: [`GET /api/v2/device/{deviceID}/attributes`](./device.md#get-device-posture-attributes)
|
||||
- Set custom device posture attributes: [`POST /api/v2/device/{deviceID}/attributes/{attributeKey}`](./device.md#set-device-posture-attributes)
|
||||
- Delete custom device posture attributes: [`DELETE /api/v2/device/{deviceID}/attributes/{attributeKey}`](./device.md#delete-custom-device-posture-attributes)
|
||||
- [**Device invites**](./device.md#invites-to-a-device)
|
||||
- List device invites: [`GET /api/v2/device/{deviceID}/device-invites`](./device.md#list-device-invites)
|
||||
- Create device invites: [`POST /api/v2/device/{deviceID}/device-invites`](./device.md#create-device-invites)
|
||||
|
||||
**[Tailnet](./tailnet.md#tailnet)**
|
||||
|
||||
- [**Policy File**](./tailnet.md#policy-file)
|
||||
- Get policy file: [`GET /api/v2/tailnet/{tailnet}/acl`](./tailnet.md#get-policy-file)
|
||||
- Update policy file: [`POST /api/v2/tailnet/{tailnet}/acl`](./tailnet.md#update-policy-file)
|
||||
- Preview rule matches: [`POST /api/v2/tailnet/{tailnet}/acl/preview`](./tailnet.md#preview-policy-file-rule-matches)
|
||||
- Validate and test policy file: [`POST /api/v2/tailnet/{tailnet}/acl/validate`](./tailnet.md#validate-and-test-policy-file)
|
||||
- [**Devices**](./tailnet.md#devices)
|
||||
- List tailnet devices: [`GET /api/v2/tailnet/{tailnet}/devices`](./tailnet.md#list-tailnet-devices)
|
||||
- [**Keys**](./tailnet.md#tailnet-keys)
|
||||
- List tailnet keys: [`GET /api/v2/tailnet/{tailnet}/keys`](./tailnet.md#list-tailnet-keys)
|
||||
- Create an auth key: [`POST /api/v2/tailnet/{tailnet}/keys`](./tailnet.md#create-auth-key)
|
||||
- Get a key: [`GET /api/v2/tailnet/{tailnet}/keys/{keyid}`](./tailnet.md#get-key)
|
||||
- Delete a key: [`DELETE /api/v2/tailnet/{tailnet}/keys/{keyid}`](./tailnet.md#delete-key)
|
||||
- [**DNS**](./tailnet.md#dns)
|
||||
- [**Nameservers**](./tailnet.md#nameservers)
|
||||
- Get nameservers: [`GET /api/v2/tailnet/{tailnet}/dns/nameservers`](./tailnet.md#get-nameservers)
|
||||
- Set nameservers: [`POST /api/v2/tailnet/{tailnet}/dns/nameservers`](./tailnet.md#set-nameservers)
|
||||
- [**Preferences**](./tailnet.md#preferences)
|
||||
- Get DNS preferences: [`GET /api/v2/tailnet/{tailnet}/dns/preferences`](./tailnet.md#get-dns-preferences)
|
||||
- Set DNS preferences: [`POST /api/v2/tailnet/{tailnet}/dns/preferences`](./tailnet.md#set-dns-preferences)
|
||||
- [**Search Paths**](./tailnet.md#search-paths)
|
||||
- Get search paths: [`GET /api/v2/tailnet/{tailnet}/dns/searchpaths`](./tailnet.md#get-search-paths)
|
||||
- Set search paths: [`POST /api/v2/tailnet/{tailnet}/dns/searchpaths`](./tailnet.md#set-search-paths)
|
||||
- [**Split DNS**](./tailnet.md#split-dns)
|
||||
- Get split DNS: [`GET /api/v2/tailnet/{tailnet}/dns/split-dns`](./tailnet.md#get-split-dns)
|
||||
- Update split DNS: [`PATCH /api/v2/tailnet/{tailnet}/dns/split-dns`](./tailnet.md#update-split-dns)
|
||||
- Set split DNS: [`PUT /api/v2/tailnet/{tailnet}/dns/split-dns`](./tailnet.md#set-split-dns)
|
||||
- [**User invites**](./tailnet.md#tailnet-user-invites)
|
||||
- List user invites: [`GET /api/v2/tailnet/{tailnet}/user-invites`](./tailnet.md#list-user-invites)
|
||||
- Create user invites: [`POST /api/v2/tailnet/{tailnet}/user-invites`](./tailnet.md#create-user-invites)
|
||||
|
||||
**[User invites](./userinvites.md#user-invites)**
|
||||
|
||||
- Get user invite: [`GET /api/v2/user-invites/{userInviteId}`](./userinvites.md#get-user-invite)
|
||||
- Delete user invite: [`DELETE /api/v2/user-invites/{userInviteId}`](./userinvites.md#delete-user-invite)
|
||||
- Resend user invite (by email): [`POST /api/v2/user-invites/{userInviteId}/resend`](#resend-user-invite)
|
||||
|
||||
**[Device invites](./deviceinvites.md#device-invites)**
|
||||
|
||||
- Get device invite: [`GET /api/v2/device-invites/{deviceInviteId}`](./deviceinvites.md#get-device-invite)
|
||||
- Delete device invite: [`DELETE /api/v2/device-invites/{deviceInviteId}`](./deviceinvites.md#delete-device-invite)
|
||||
- Resend device invite (by email): [`POST /api/v2/device-invites/{deviceInviteId}/resend`](./deviceinvites.md#resend-device-invite)
|
||||
- Accept device invite [`POST /api/v2/device-invites/-/accept`](#accept-device-invite)
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,147 +0,0 @@
|
||||
> [!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](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