mirror of
https://github.com/tailscale/tailscale.git
synced 2025-01-10 01:53:49 +00:00
6831a29f8b
This change creates a new folder called publicapi that will become the future home to the Tailscale public API docs. This change also splits the existing API docs (still located in api.md) into separate files, for easier reading and contribution. Updates tailscale/corp#19526 Signed-off-by: Charlotte Brandhorst-Satzkorn <charlotte@tailscale.com>
100 lines
5.6 KiB
Markdown
100 lines
5.6 KiB
Markdown
# 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)
|
|
|
|
**[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)
|