> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tailscale

> Connect Tailscale to Serval with an API access token to automate device, network, and security & compliance workflows across your tailnet

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

<CardGroup cols={2}>
  <Card title="Key Features" icon="network-wired">
    * 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
  </Card>

  <Card title="Common Use Cases" icon="wand-magic-sparkles">
    * Device compliance and posture assessment
    * Network access auditing and incident investigation
    * Auth key inventory and rotation reviews
    * Change tracking across the tailnet
  </Card>
</CardGroup>

Anything defined in the [Tailscale API](https://tailscale.com/api) can be accessed through Serval.

## Prerequisites

Before setting up the Tailscale integration, ensure you have:

<Steps>
  <Step title="Tailscale Account">
    An active Tailscale account with admin access to your tailnet.
  </Step>

  <Step title="API Access Token">
    An API access token created from the Tailscale admin console (see Step 1 below). Tokens are prefixed with `tskey-api-`.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Setup Instructions

### Step 1: Generate a Tailscale API Access Token

<Steps>
  <Step title="Open the Keys page">
    Log in to the Tailscale admin console and go to [**Settings → Keys**](https://login.tailscale.com/admin/settings/keys).
  </Step>

  <Step title="Generate an access token">
    Click **Generate access token**, give it a descriptive name (e.g. `Serval Integration`), and choose an expiry.
  </Step>

  <Step title="Copy the token">
    Copy the generated token. It is prefixed with `tskey-api-` and is shown only once.
  </Step>
</Steps>

<Warning>
  **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.
</Warning>

### Step 2: Configure the Integration in Serval

1. In Serval go to **Apps → Available → Tailscale → Connect**
2. Enter your configuration details:

<Info>
  <ParamField body="Instance Name" type="string" required>
    A friendly label for this connection, such as `Acme Tailnet`. Used to identify the integration in Serval.
  </ParamField>

  <ParamField body="API Key" type="string" required>
    The Tailscale API access token from Step 1 (prefixed with `tskey-api-`). This authenticates all API requests.
  </ParamField>

  <ParamField body="Tailnet" type="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.
  </ParamField>
</Info>

3. Click **Submit** to establish the integration

<Check>
  Integration configured! Serval authenticates requests to `api.tailscale.com` with your token using a Bearer authorization header.
</Check>

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

<AccordionGroup>
  <Accordion title="Device Management">
    * **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)
  </Accordion>

  <Accordion title="Network Info">
    * **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
  </Accordion>

  <Accordion title="Security & Compliance">
    * **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)
  </Accordion>
</AccordionGroup>

### 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

<Info>
  **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.
</Info>

<Note>
  **Pagination**: The Tailscale API does not currently support pagination — list endpoints return all results at once.
</Note>

## Additional Resources

<CardGroup cols={2}>
  <Card title="Tailscale API Documentation" icon="book" href="https://tailscale.com/api">
    Complete API reference for all Tailscale endpoints
  </Card>

  <Card title="Manage API Access Tokens" icon="key" href="https://login.tailscale.com/admin/settings/keys">
    Generate and rotate access tokens in the Tailscale admin console
  </Card>
</CardGroup>

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your Tailscale integration.