Join us in San Francisco for TailscaleUp!Grab your ticket ->

Create API-only tailnets

Last validated:
Tailnet creation APIs are currently in alpha.
Tailnet creation APIs are available for all plans. You can create up to ten total tailnets in your organization, including your original tailnet. If your use case requires more than ten tailnets, contact Tailscale Sales.

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. Tailnets created with these APIs support only tagged devices. They're great for building directly into your applications, automations, and infrastructure, but they aren't appropriate for use cases that require a human to join the tailnet directly.

You can use API-only tailnets to:

  • Create an ephemeral tailnet as part of a CI/CD pipeline
  • Build private connectivity into your applications
  • Deploy sandbox tailnets for AI agents

If you're trying to create additional tailnets that appear in the admin console and support human users, refer to Manage multiple tailnets.

Authentication

You can only authenticate these tailnet creation APIs with an OAuth client. You must create the OAuth client in an existing tailnet.

  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.

Authenticate against API-only tailnets

When you create a new API-only tailnet, the response contains details for an OAuth client that permits access to the API for that tailnet.

Additionally, an OAuth client in the creating tailnet can obtain a new OAuth access token with access to the API-only tailnet by specifying the tailnet's ID in the tailnet parameter to our /token endpoint. The OAuth client must have the all scope. You can use this method to retrieve new credentials for an API-only tailnet if you lose the OAuth client credentials that were returned in the original creation response.

For example:

 curl -d "client_id=${OAUTH_CLIENT_ID}" -d "client_secret=${OAUTH_CLIENT_SECRET}" \
     "https://api.tailscale.com/api/v2/oauth/token?tailnet=T123456CNTRL"

Endpoints

For endpoint paths, request schemas, response schemas, status codes, and required OAuth scopes, refer to the Tailscale API reference:

If you lose the OAuth client credentials returned when creating an API-only tailnet, or want to create additional credentials for that tailnet, authenticate against the API-only tailnet using an OAuth client from the creating tailnet, then use it to create a new OAuth client in the API-only tailnet.

Configure API-only tailnets

Once an API-only tailnet has been created, our standard public API endpoints can be used to write access policies, customize settings, and authenticate new tagged devices to the tailnet.

Limitations

  • Alpha API endpoints are not considered stable interfaces. Tailscale will communicate with users before making breaking changes.
  • These alpha endpoints are 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. 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.