Skip to main content

​
About Tailscale

Tailscale is a mesh VPN built on WireGuard that connects your organization’s devices, servers, and services into a private network called a tailnet. The Serval Tailscale integration connects to the Tailscale API with an API access token, giving workflows access to device management, user and DNS lookups, ACL policy review, device posture attributes, auth-key inventory, tailnet settings, and configuration audit logs. Serval only ever talks to Tailscale’s official API address (api.tailscale.com), using the token you provide. A single connection ships with 15 prebuilt workflows across 3 bundles: Device Management, Network Info, and Security & Compliance. Authentication: Tailscale API access token (API key). Serval stores the token securely and attaches it to every Tailscale request your workflows make as a Bearer authorization header. Data sync: On-demand only. Serval calls the Tailscale API when a workflow or health check runs - there is no background sync, polling, or webhook ingestion.

​
What the Tailscale integration enables

CapabilityDescription
Device managementList all tailnet devices (hostname, OS, IPs, online status), inspect a single device, view its advertised and enabled subnet routes, and read its posture attributes. Write actions can authorize or deauthorize a device, expire a device’s node key to force re-authentication, and set device tags (replacing existing tags). The three write workflows default to installer approval; reads require no approval by default.
User lookupList all users in your tailnet with role, status, and login information, or look up a specific user. No approval required by default.
DNS configurationView the tailnet’s global DNS nameservers and DNS preferences, including MagicDNS status. Read-only.
Security and compliancePull the full ACL policy file (access rules, groups, tag owners, posture conditions), list configuration audit logs (who changed what and when), inventory all auth keys (capabilities, expiration, revocation status), and read tailnet-wide settings such as auto-updates, key duration, user approval, network flow logging, and posture identity collection. Combine the ACL policy with device posture attributes to evaluate whether a device meets posture requirements.
Anything defined in the Tailscale API can be accessed through Serval.

​
Get your credentials

Serval connects with a Tailscale API access token, which must be generated by a tailnet Owner, Admin, IT admin, or Network admin. The token inherits the permissions of the user who creates it, so generate it from an account with the access your workflows need - one whose role can manage devices in the Tailscale admin console if you plan to use write actions like Authorize Device, Expire Device Key, or Set Device Tags. For background, see Tailscale’s key and secret management documentation.
1

Open the Keys page

Sign in to the Tailscale admin console and open the Keys page.
2

Generate an access token

Find the API access tokens section and select Generate access token. Give it a descriptive name (for example “Serval Integration”).
3

Choose an expiry

Pick an expiry between 1 and 90 days. Tokens cannot be renewed - when this one expires, you will generate a new one and update your Serval connection.
4

Copy the token immediately

The token starts with “tskey-api-” and is displayed in full only once. Copy it now - it cannot be retrieved later.
5

Optional: note your tailnet ID

If you want to pin the connection to a specific tailnet instead of the token’s default, copy your tailnet ID (for example “T1234CNTRL”) from the General Settings page.
Tailscale shows the token exactly once. If you lose it before saving it in Serval, you will need to generate a new one.
Most single-tailnet organizations can skip the tailnet ID entirely - Tailscale automatically uses the token’s default tailnet.

​
Connect in Serval

1

Start the connection

In Serval, open the Tailscale integration and start a new connection.
2

Instance Name (optional)

Enter a label for this connection, such as “Production tailnet”. Free text, no validation. The name also serves as the connection’s internal identifier, so pick a stable name up front.
3

API Key (optional in the form, required in practice)

Paste your full Tailscale API access token (it starts with “tskey-api-”). This is a password field and is shown obfuscated after saving, with only the last 4 characters visible. The form does not block submission if you leave it empty - a blank or mistyped token is accepted at save time and only surfaces when the connection health check runs.
4

Tailnet (optional)

The field shows the placeholder “e.g. example.com or - for default”. Leave it blank (or enter ”-”) to use the token’s default tailnet. To target a specific tailnet, enter the tailnet ID from the admin console’s General Settings page (for example “T1234CNTRL”). Name-style values like “example.com” only work for tailnets created before October 2025.
5

Save

Save the connection. On success you will see “Tailscale connected successfully” and Serval automatically runs the connection health check. The API key is then displayed as bullets plus its last 4 characters. If the save itself fails, you will see a general error such as “Failed to connect service” or a message starting with “Failed to install integration”.
When you later edit this connection for any reason, re-enter the full API key (and your Tailnet value, if you set one) before saving. Do not clear pre-filled fields or save with the API key field showing only the obfuscated placeholder - always paste the complete token again when rotating credentials or changing any setting. Update failures surface as “Failed to update integration:” or “Failed to update configuration”.

​
Verifying the connection

After you connect, Serval automatically runs the connection health check. It asks Tailscale for the device list of your configured tailnet (or the token’s default tailnet when the Tailnet field is blank). A passing check confirms the token is valid and can read your tailnet’s devices. Tailscale has no Serval-specific failure messages - if the check fails, you will see the raw error returned by the Tailscale API, including the request URL, status code, and response body. As a rule of thumb:
  • An error mentioning 401 means the token is invalid, expired, or revoked. Generate a new token and update the connection (re-entering all fields).
  • A failed tailnet-scoped check usually means the Tailnet value is wrong. Use the tailnet ID from General Settings, or leave the field blank.
A passing health check only proves read access. If the check is green but workflows like Authorize Device, Expire Device Key, or Set Device Tags fail with an error mentioning 403, the user who created the token lacks the admin rights to manage devices - generate a new token from an account whose role can manage devices in the Tailscale admin console.

​
Prebuilt workflows

Serval ships 15 prebuilt Tailscale workflows grouped into three bundles. Workflows that change state (authorize, expire key, set tags) default to requiring installer approval before they run; the read-only workflows require no approval by default.
  • 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 plus 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 (for example 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.

​
Gotchas and troubleshooting

When you open a saved connection, the API key appears as an obfuscated placeholder. Saving an edit without pasting the full token again - or with a cleared Tailnet field - can break the connection. Whenever you change anything on this connection, re-enter the complete API key and your Tailnet value (if you use one) before saving.
Plan a rotation routine: generate a new token on the Tailscale Keys page before the old one expires, then update the Serval connection, re-entering all fields. The token also inherits its creator’s permissions - read workflows need only read access, but Authorize Device, Expire Device Key, and Set Device Tags need an account whose role can manage devices. Those three write workflows default to installer approval in Serval.
When the Tailnet field is blank, the connection health check uses ”-”, which Tailscale resolves to the access token’s default tailnet. The prebuilt tailnet-scoped workflows ask for a tailnet value on each run - entering ”-” targets the token’s default tailnet, and when you do set a Tailnet on the connection, Serval makes that value available to workflow runs. For most single-tailnet setups, blank is correct. If you do fill it in, prefer the tailnet ID (for example “T1234CNTRL”) from the admin console’s General Settings page - legacy names like “example.com” only work for tailnets created before October 2025.
There are no friendly Serval-specific error messages for Tailscale. An error mentioning 401 means an invalid, expired, or revoked token; 403 on write workflows means the token’s owning user lacks the admin rights for that action; a failed tailnet-scoped call usually means a wrong Tailnet value.
None of the three fields are marked required, and nothing is tested at save time - the form lets you submit without an API key, and the connection is created anyway. The mistake only surfaces when the credential is first used: the health check fails (or the first workflow run errors with a 401). If you see that, edit the connection and paste a valid token, re-entering all fields.
The Tailscale API does not support pagination, so list workflows (devices, users, auth keys, audit logs) return all results in a single response. For large tailnets, expect big result sets. The audit log workflow is bounded only by the start and end times you give it.
Authorizing or deauthorizing only applies on tailnets where device authorization is required - on tailnets without that setting, it has no gating effect. Deauthorizing a device prevents it from connecting.

​
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.