Skip to main content

​
Overview

The Tailscale integration lets you automate device management, network configuration auditing, and security & compliance workflows across your tailnet. Connect Serval to Tailscale to inventory devices, review ACL policies, audit configuration changes, and evaluate device posture against your access policies.

Key Features

  • List and inspect tailnet devices, routes, and posture attributes
  • Authorize, deauthorize, and tag devices; expire device keys
  • Review ACL policy, auth keys, and tailnet settings
  • Pull configuration audit logs for compliance evidence

Common Use Cases

  • Device compliance and posture assessment
  • Network access auditing and incident investigation
  • Auth key inventory and rotation reviews
  • Change tracking across the tailnet
Anything defined in the Tailscale API can be accessed through Serval.

​
Prerequisites

Before setting up the Tailscale integration, ensure you have:
1

Tailscale Account

An active Tailscale account with admin access to your tailnet.
2

API Access Token

An API access token created from the Tailscale admin console (see Step 1 below). Tokens are prefixed with tskey-api-.
3

Tailnet (optional)

The tailnet you want to operate on. Most users can leave this blank to use the default tailnet of the token. You can find your tailnet ID on the General Settings page of the Tailscale admin console.

​
Setup Instructions

​
Step 1: Generate a Tailscale API Access Token

1

Open the Keys page

Log in to the Tailscale admin console and go to Settings → Keys.
2

Generate an access token

Click Generate access token, give it a descriptive name (e.g. Serval Integration), and choose an expiry.
3

Copy the token

Copy the generated token. It is prefixed with tskey-api- and is shown only once.
Token Security: Store the access token securely and never expose it in client-side code or public repositories. Serval keeps it in encrypted credential storage. Tokens expire — set a calendar reminder to rotate before expiry so workflows don’t break.

​
Step 2: Configure the Integration in Serval

  1. In Serval go to Apps → Available → Tailscale → Connect
  2. Enter your configuration details:
​
Instance Name
string
required
A friendly label for this connection, such as Acme Tailnet. Used to identify the integration in Serval.
​
API Key
string
required
The Tailscale API access token from Step 1 (prefixed with tskey-api-). This authenticates all API requests.
​
Tailnet
string
Optional. The tailnet to operate on, such as example.com. Leave blank (or use -) to reference the default tailnet of the access token — recommended for most users. Specify a tailnet ID only if you operate across multiple tailnets.
  1. Click Submit to establish the integration
Integration configured! Serval authenticates requests to api.tailscale.com with your token using a Bearer authorization header.

​
Available Workflows

Serval ships prebuilt Tailscale workflows grouped into three bundles. Workflows that change state (authorize, expire key, set tags) default to requiring installer approval before they run.
  • List Tailnet Devices — list all devices, including hostname, OS, IP addresses, and online status
  • Get Device — retrieve detailed information about a specific device
  • List Device Routes — list subnet routes advertised and enabled for a device
  • Get Device Posture Attributes — retrieve a device’s posture attributes (custom and provider-managed) used for compliance and access policy evaluation
  • Authorize Device — authorize or deauthorize a device on a tailnet that requires device authorization
  • Expire Device Key — mark a device’s node key as expired, forcing re-authentication
  • Set Device Tags — set the tags used in ACL policies for a device (replaces existing tags)
  • List Tailnet Users — list all users with their role, status, and login information
  • Get User — retrieve detailed information about a specific user
  • List DNS Nameservers — list the global DNS nameservers configured for the tailnet
  • Get DNS Preferences — retrieve DNS preferences, including MagicDNS status
  • Get ACL Policy — retrieve the tailnet’s ACL policy file (access rules, groups, tag owners, posture conditions, network segmentation)
  • List Configuration Audit Logs — time-bounded record of configuration changes for compliance reviews and incident investigation
  • List Auth Keys — list auth keys with their capabilities, expiration, and revocation status for credential inventory and rotation audits
  • Get Tailnet Settings — retrieve tailnet-wide settings (auto-updates, key duration, user approval, network flow logging, posture identity collection)

​
Compliance: ACL Policy + Device Posture

The Get ACL Policy and Get Device Posture Attributes workflows combine to evaluate whether a device meets the posture requirements defined in your ACL:
  1. Retrieve the ACL policy to see which posture conditions are defined and which grants depend on them (e.g. posture:highTrust requiring falcon:ztaScore >= 80).
  2. Retrieve a device’s posture attributes to see its current values.
  3. Compare the device’s attributes against the ACL conditions to determine which network grants it qualifies for.
This supports compliance reviews, incident investigation, and verifying that devices meet security baselines before accessing sensitive network segments.

​
Additional Notes

Tailnet parameter: When a workflow needs a {tailnet} value and the integration’s Tailnet field is blank, Serval uses -, which references the default tailnet of the access token.
Pagination: The Tailscale API does not currently support pagination — list endpoints return all results at once.

​
Additional Resources

Tailscale API Documentation

Complete API reference for all Tailscale endpoints

Manage API Access Tokens

Generate and rotate access tokens in the Tailscale admin console
Need help? Contact support@serval.com for assistance with your Tailscale integration.