Skip to main content

CREATE A TAGGED, PREAUTHORIZED TAILSCALE AUTH KEY

This guide shows you how to create a Tailscale auth key that is reusable, ephemeral and preauthorized, and that tags every device that joins with it. Swamp keeps the key secret in a vault.

Prerequisites

  • A Tailscale credential for the tailnet. Set TAILSCALE_API_KEY to an API access token, or set TAILSCALE_OAUTH_CLIENT_ID and TAILSCALE_OAUTH_CLIENT_SECRET to an OAuth client's ID and secret
  • The credential must be allowed to assign the tags you put on the key

Pull the extension

swamp extension pull @swamp/tailscale

The output looks like:

INF extension·pull: Pulling "@swamp/tailscale"@"2026.10.13.1"
INF extension·pull: Identity verified: "@swamp/tailscale"@"2026.10.13.1"
INF extension·pull: Pulled "@swamp/tailscale"@"2026.10.13.1"
INF extension·pull: Extracted 54 files:

Define the key

Create a behavior of type @swamp/tailscale/tailnet-key named ci-auth-key (see Create and Run a Behavior) with these global arguments:

globalArguments:
  name: ci-auth-key
  description: CI runners
  capabilities:
    devices:
      create:
        reusable: true
        ephemeral: true
        preauthorized: true
        tags:
          - tag:ci

name is required. It is the instance name that identifies this key within the behavior. Adjust the rest to fit your use:

  • For a key that can be used only once, set reusable to false
  • To keep devices in the tailnet when they go offline, set ephemeral to false
  • To have an admin approve each device, set preauthorized to false
  • To expire the key earlier or later than the 90-day default, set expirySeconds

To read the API token from a vault instead of the environment, add it to the definition:

globalArguments:
  apiKey: "${{ vault.get('default', 'tailscale-api-key') }}"

Create the key

swamp behavior run ci-auth-key create

This command creates the auth key in the tailnet and writes its state to the behavior's data. It writes the key secret, which Tailscale returns only at creation, to a vault. To choose which vault receives the secret, see Route Sensitive Fields to Specific Vaults.

List the tailnet's auth keys

swamp behavior run ci-auth-key list

This command lists every auth key in the tailnet, including keys created outside Swamp, and writes each one to the behavior's state.

To bring an existing key under this behavior, run the adopt method with the key's id. To revoke the key, run delete. See the Tailscale extensions reference for every method on @swamp/tailscale/tailnet-key.