Tailnet creation API

Tailscale provides API endpoints that you can use to create and list multiple Tailscale networks (known as tailnets) in your organization. These tailnets are considered API-only, meaning that they do not contain human users or appear in the admin console. As a result, tailnets created with these APIs are great for building directly into your applications and infrastructure, but are not appropriate for use cases that require a human to join the tailnet directly.

Authentication

You can only authenticate these tailnet creation APIs with an OAuth client. You must create the OAuth client in an existing tailnet that's pre-approved to use these APIs.

1. Generate an OAuth client with the tailnets scope.
2. Exchange the OAuth client secret for an API access token that can be provided to the API endpoints.

Endpoints

Create a new tailnet

Request

curl https://api.tailscale.com/api/v2/organizations/-/tailnets \
  --request POST \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{"displayName": "<displayName>"}'

• displayName: A custom name for the tailnet that you provide. It can contain letters, numbers, spaces, apostrophes, and hyphens. This name must be unique within your organization.

Response

{
  "id": "T123456CNTRL",
  "displayName": "<displayName>",
  "orgId": "o123456CNTRL",
  "dnsName": "tail1234.ts.net",
  "createdAt": "2025-01-01T12:00:00Z",
  "oauthClient": {
    "id": "k123456CNTRL",
    "secret": "tskey-client-xxxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}

• id: A stable, globally-unique identifier for the tailnet.
• displayName: The tailnet name you provided.
• orgId: A stable, globally-unique identifier for your organization.
• dnsName: The DNS suffix used to construct fully qualified domain names for devices in this tailnet.
• createdAt: When the tailnet was created, represented as an ISO 8601 datetime string.
• oauthClient: An OAuth client with the all scope that permits changing the new tailnet's settings or authenticating devices to the tailnet using our public API. You should store this OAuth client immediately because you cannot regenerate or retrieve it again.

Get all tailnets

Request

curl https://api.tailscale.com/api/v2/organizations/-/tailnets \
  --request GET \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

Response

The endpoint returns a tailnets object containing an array of all the tailnets in your organization. This will include your original tailnet as well as any tailnets created with these API endpoints.

{
  "tailnets": [
    {
      "id": "T123456CNTRL",
      "displayName": "<displayName>",
      "orgId": "o123456CNTRL",
      "createdAt": "2025-01-01T12:00:00Z"
    }
  ]
}

• id: A stable, globally-unique identifier for the tailnet.
• displayName: The tailnet name you provided.
• orgId: A stable, globally-unique identifier for your organization.
• createdAt: When the tailnet was created, represented as an ISO 8601 datetime string.

Limitations

• These alpha endpoints are not considered stable interfaces. Tailscale will communicate with users before making breaking changes.
• These alpha endpoints are private and are therefore not available in our API's Go client, Terraform provider, or Pulumi provider.
• Tailnets created with these API endpoints have no human owner or users. You must use the public API to interact with the tailnet, using the OAuth credential that is returned when creating the tailnet for the first time. Future iterations of this feature will remove this limitation.
• Tailnets created with these API endpoints do not appear in the admin console for your organization. Future iterations of this feature will let you choose if these tailnets should appear in the admin console.