Tailscale PAM service accounts

Service accounts are machine identities that let AI agents and applications interact with Tailscale PAM.

You can use service accounts for two primary purposes:

• Manage Tailscale PAM programmatically: Create a service account and token for automation that uses the Tailscale PAM API, such as Terraform or scripts that manage services, connectors, policies, or session data.
• Access an HTTP service without the Tailscale client: Tailscale tags are represented in PAM as client service accounts. You can create a token for one of these identities when a workload needs clientless access to an HTTP service.

For other machine-to-machine access to PAM services, use a tagged device running Tailscale. Tailscale tags provide identities for non-user devices and let you control their access through your tailnet policy.

Service accounts and Tailscale tags

Tailscale PAM automatically represents each Tailscale tag as a service account with the client role. You can find these identities in the PAM settings page of the admin console, under Service accounts.

You don't need to create a PAM service account for a tagged device. If the workload has the Tailscale client installed, use its tag identity to access PAM services.

A token is only needed for a tag-backed client service account when a workload programmatically accesses an HTTP service without the Tailscale client. Other PAM service types do not require a service account token.

The client role lets the identity act as a client of PAM services. It doesn't provide permission to manage PAM configuration, and the identity must still be allowed to access the target service by your tailnet policy file.

Create a service account for API access

Create a service account when an application, script, or automation tool needs to manage Tailscale PAM resources programmatically.

For example, you can use a service account with Terraform to create and manage PAM services, connectors, and policies. Tailscale PAM currently uses the Border0 Terraform provider for this workflow.

To create a service account:

1. Open the PAM settings page.
2. In the Service accounts section, select Add service account.
3. Enter a Name for the service account.
4. (Optional) Enter a description.
5. Select the role that provides the permissions required by your automation.
6. Select Add service account.

For Terraform configurations that manage services and connectors, use the Member role. For more limited automation, select a more restrictive role when possible.

Service account roles

Select the least-privileged role that provides the access your automation requires.

These roles determine what the service account can do through the Border0 API used by Tailscale PAM.

For automation such as Terraform, choose the narrowest role that covers the resources managed by your configuration.

Create a service account token

After creating the service account, create a token that your application can use to authenticate to the Border0 API used by Tailscale PAM.

To create a token:

1. Open the PAM settings page.
2. In the Service accounts section, find the service account, select the menu, and select Edit.
3. Select Create token.
4. Enter a name for the token.
5. Select the token lifetime.
6. Select Save.
7. Copy the token and store it securely.

Treat service account tokens as secrets. The token inherits the permissions of its service account.

When possible, use an expiring token and choose the shortest lifetime that works for your automation.

Use a service account with the Tailscale PAM API

Tailscale PAM currently uses the Border0 API at https://api.border0.com for programmatic management. Authentication for this API is separate from authentication for the Tailscale API.

Use the token created for your PAM service account to authenticate API requests.

For example:

curl https://api.border0.com/api/v1/connectors \
  -H "accept: application/json" \
  -H "Authorization: <your-token>"

Replace <your-token> with the token that you created.

The permissions available to the application are determined by the role assigned to the service account.

Use Terraform with Tailscale PAM

You can use the Border0 Terraform provider to manage Tailscale PAM resources as infrastructure as code.

Create a PAM service account with the permissions required by your Terraform configuration, create a token for that service account, and use the token to authenticate the provider.

Refer to the following resources for provider configuration and examples:

• Border0 Terraform provider documentation
• Border0 Terraform examples

The Terraform provider and examples currently use Border0 API and resource terminology. For example, resources that appear as services of the Tailscale admin console might be called sockets in the Terraform provider.

Access an HTTP service with a client service account

HTTP services can be accessed programmatically without installing the Tailscale client on the requesting machine. For this use case, create a token for the tag-backed client service account that represents the workload's Tailscale identity.

You don't need to create another service account.

To create the token:

1. Open the PAM settings page.
2. In the Service accounts section, find the service account corresponding to the Tailscale tag you want to use. Tag-backed identities have the client role.
3. Select the menu, and select Edit.
4. Select Create token.
5. Enter a name for the token.
6. Select the token lifetime.
7. Select Save.
8. Copy the token.

Pass the token to the HTTP service using the Border0-Token request header, replacing <your-token> with the token that you created. :

export BORDER0_TOKEN=<your-token>

curl https://nginx1-demo.border0.io \
  -H "Border0-Token: $BORDER0_TOKEN"

Tailscale PAM uses the Border0-Token header instead of the standard Authorization header so that PAM authentication doesn't conflict with authentication headers required by the upstream HTTP application.

The token identifies the request as the corresponding tagged client identity. Creating a token does not grant additional access. Your tailnet policy file still determines which PAM services that identity can use.

Best practices to protect service account tokens

Service account tokens provide non-human access to PAM resources, so protect them like other privileged credentials.

• Use the least-privileged service account role appropriate for the workload.
• Prefer expiring tokens instead of tokens that never expire.
• Store tokens in a secrets manager or another secure credential store instead of source code or configuration files.
• Create separate service accounts or tokens for separate automation workloads when doing so makes ownership and rotation clearer.
• Remove tokens that are no longer required, and replace a token if you believe it has been exposed.