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 OAuth client or 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 credentials you provide. A single connection ships with 15 prebuilt workflows across 3 bundles: Device Management, Network Info, and Security & Compliance. Authentication: Tailscale OAuth client or API access token. An OAuth client is recommended - it never expires, and Serval uses its client ID and secret to automatically mint short-lived API tokens as needed. An API access token expires after at most 90 days. Either way, Serval stores the credentials securely and attaches a Bearer authorization header to every Tailscale request your workflows make. 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

Anything defined in the Tailscale API can be accessed through Serval.

​
Get your credentials

Serval supports two Tailscale credential types. Both must be created by a tailnet Owner, Admin, IT admin, or Network admin. For background, see Tailscale’s key and secret management documentation.
  • OAuth client (recommended): never expires. Serval uses it to automatically mint short-lived API tokens as needed, so there is no rotation routine to maintain. Its permissions are the scopes you select on the client.
  • API access token: expires after 1 to 90 days and can’t be renewed. It inherits the permissions of the user who creates it.

​
OAuth client

Serval requests tokens without naming specific scopes, so every token carries all the scopes configured on the client. You decide what Serval can do in Tailscale by choosing scopes on the client at creation time.
1

Open the OAuth clients page

Sign in to the Tailscale admin console and open the OAuth clients page, under Settings > Trust credentials.
2

Generate an OAuth client

Select Generate OAuth client and give it a recognizable description (for example “Serval Integration”).
3

Select scopes

Grant at least devices:core:read - the connection health check reads your tailnet’s device list. Then add scopes for the workflows you plan to run:
  • devices:core (write) for Authorize Device, Expire Device Key, and Set Device Tags
  • dns:read for the DNS nameserver and preference workflows
  • feature_settings:read for Get Tailnet Settings
  • auth_keys:read for the auth-key inventory
The scope picker lists everything else - grant the scopes that cover your remaining workflows.
4

Copy the client ID and client secret

The client secret starts with “tskey-client-” and is displayed in full only once. Copy both values now.

​
API access token

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.
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 can’t 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 can’t be retrieved later.
Whichever credential type you choose, you can pin the connection to a specific tailnet instead of the credential’s default: copy your tailnet ID (for example “T1234CNTRL”) from the General Settings page.
Tailscale shows the client secret or access 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 credential’s default tailnet.

​
Connect in Serval

1

Start the connection

In Serval, open the Tailscale integration and start a new connection. Already connected and switching to an OAuth client? Don’t create a second connection - open your existing Tailscale connection’s settings and edit it there instead: choose OAuth client, paste the credentials, and save. Editing upgrades the existing connection in place, while creating a new one can leave the old credential active.
2

Instance Name

Enter a label for this connection, such as “Production tailnet.” Leave it blank and Serval names the connection “Tailscale.” The name also serves as the connection’s internal identifier, so pick a stable name up front.
3

Authentication method

Choose OAuth client or API access token (expires after at most 90 days). The form shows the credential fields for the method you pick.
4

OAuth client: Client ID and Client Secret

Paste the OAuth client’s ID and its secret (the secret starts with “tskey-client-”). Both are password fields and are shown obfuscated after saving, with only the last 4 characters visible.
5

API access token: token

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

Tailnet (optional)

The field’s placeholder text shows the accepted formats. Leave it blank (or enter ”-”) to use the credential’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.
7

Save

Save the connection. The form marks the chosen method’s credential fields as required, and Serval validates the values server-side too - a missing credential, or one whose prefix belongs to the other method, is rejected with a message that points at the right method. It doesn’t call Tailscale at save time, so a mistyped credential only surfaces when the connection health check runs. On success you will see “Tailscale connected successfully” and Serval automatically runs the health check. If the save fails for another reason, you will see a general error such as “Failed to connect service” or a message starting with “Failed to install integration.”
When you edit this connection later, secrets you leave untouched are preserved - saving with a field still showing its obfuscated placeholder keeps the stored value. Paste a new value only for the credential you are rotating. To switch authentication methods, pick the new method and supply its full credentials.

​
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 credential’s default tailnet when the Tailnet field is blank). A passing check confirms the credentials are valid and can read your tailnet’s devices - for an OAuth client, that requires the devices:core:read scope. 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 credential is no longer valid: an expired or revoked API access token, or a revoked OAuth client. Generate a new credential and update the connection.
  • 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 credential lacks device-management rights. For an API access token, generate a new one from an account whose role can manage devices in the Tailscale admin console. For an OAuth client, add the devices:core write scope.

​
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 the 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 a device, or revoke its authorization, 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 name servers 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 (automatic 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, secrets - the OAuth client ID included - appear as obfuscated placeholders. Saving without changing them keeps the stored values - paste a new value only for the credential you are rotating. A blank Instance Name or Tailnet also keeps the existing value. To switch authentication methods, select the new method and supply its full credentials. One quirk: you can’t clear a stored Tailnet back to blank - enter ”-” to target the credential’s default tailnet instead. Update failures surface as “Failed to update integration:” or “Failed to update configuration.”
If you connect with an API access token, plan a rotation routine: generate a new token on the Tailscale Keys page before the old one expires, then paste it into the Serval connection - other fields can stay as they are. To retire the routine entirely, edit the existing connection and switch it to an OAuth client, which never expires. Permissions differ too: an access token inherits its creator’s permissions, while an OAuth client has exactly the scopes you configured on it. Read workflows need only read access, but Authorize Device, Expire Device Key, and Set Device Tags need device-management rights - for OAuth clients, the devices:core write scope. 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 credential’s default tailnet. The prebuilt tailnet-scoped workflows ask for a tailnet value on each run - entering ”-” targets the credential’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 credential. A 403 on write workflows means the credential lacks the rights for that action - the token’s owning user can’t manage devices, or the OAuth client is missing the devices:core write scope. A failed tailnet-scoped call usually means a wrong Tailnet value.
Serval rejects a save missing the chosen method’s credentials (Client ID and Client Secret, or the API access token) with a validation message. Saving also checks the credential prefixes: an API access token must start with “tskey-api-” and an OAuth client secret with “tskey-client-” - if the two are swapped, the validation message points you at the right method. A blank Instance Name isn’t an error - Serval names the connection “Tailscale.” It doesn’t call Tailscale to test the values, so a mistyped credential with the right prefix is accepted at save time and only surfaces when the health check fails or the first workflow run errors with a 401. If you see that, edit the connection and paste a valid credential.
The Tailscale API doesn’t 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 a device, or revoking its authorization, only matters on tailnets where device authorization is required - on tailnets without that setting, it has no gating effect. Revoking authorization prevents a device from connecting.

​
Additional resources

Tailscale API Documentation

Complete API reference for all Tailscale endpoints

Manage OAuth Clients

Generate OAuth clients and choose their scopes in the Tailscale admin console

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.