Key Management¶

Key Types¶

Auth Keys¶

Pre-authentication keys for automated device registration.

# Use auth key instead of browser login
sudo tailscale up --auth-key=tskey-auth-xxxxx

API Keys¶

Keys for Tailscale API access.

# API requests
curl -H "Authorization: Bearer tskey-api-xxxxx" \
  https://api.tailscale.com/api/v2/tailnet/-/devices

Auth Keys¶

Creating Auth Keys¶

Admin Console → Settings → Keys
Click Generate auth key
Configure options:
Reusable: Use for multiple devices
Ephemeral: Devices removed when offline
Pre-authorized: Skip admin approval
Expiration: 1 day to 90 days
Tags: Apply tags automatically

Auth Key Options¶

Option	Description	Use Case
One-time	Single use, then expires	Single server setup
Reusable	Multiple devices	Fleet deployment
Ephemeral	Device removed when offline	Temporary/CI jobs
Pre-authorized	No admin approval needed	Automated setup

Auth Key Expiration¶

Minimum: 1 day
Maximum: 90 days
Default: 90 days
Expired keys stop working for new registrations

Auth Key with Tags¶

# Key configured with tag:server in admin console
sudo tailscale up --auth-key=tskey-auth-xxxxx

# Device automatically tagged as "server"

Or specify tags at registration:

sudo tailscale up --auth-key=tskey-auth-xxxxx --advertise-tags=tag:webserver

API Keys¶

Creating API Keys¶

Admin Console → Settings → Keys
Click Generate API key
Select scopes
Set expiration

API Scopes¶

Scope	Permissions
`all:read`	Read all resources
`devices:read`	Read device list
`devices:write`	Modify devices
`dns:read`	Read DNS config
`dns:write`	Modify DNS
`routes:read`	Read routes
`routes:write`	Modify routes
`acl:read`	Read ACL
`acl:write`	Modify ACL

Using API Keys¶

# List devices
curl -s \
  -H "Authorization: Bearer tskey-api-xxxxx" \
  "https://api.tailscale.com/api/v2/tailnet/-/devices" | jq

# Delete a device
curl -X DELETE \
  -H "Authorization: Bearer tskey-api-xxxxx" \
  "https://api.tailscale.com/api/v2/device/{deviceID}"

# Get ACL
curl -s \
  -H "Authorization: Bearer tskey-api-xxxxx" \
  "https://api.tailscale.com/api/v2/tailnet/-/acl"

OAuth Clients¶

For applications and integrations:

Creating OAuth Clients¶

Admin Console → Settings → OAuth clients
Click Create OAuth client
Configure:
Name
Scopes
Redirect URIs (if applicable)

OAuth Scopes¶

Scope	Description
`devices`	Device management
`routes`	Route management
`dns`	DNS configuration
`acl`	ACL management
`auth_keys`	Auth key management

Using OAuth¶

# Get access token
curl -X POST \
  -d "client_id=xxx&client_secret=xxx&grant_type=client_credentials" \
  https://api.tailscale.com/oauth/token

# Use access token
curl -H "Authorization: Bearer <access_token>" \
  https://api.tailscale.com/api/v2/tailnet/-/devices

Device Keys¶

Key Expiry¶

By default, device keys expire and require re-authentication.

Disable expiry for servers: 1. Machines → Select device 2. Disable key expiry

Re-authentication¶

# Force re-authentication
sudo tailscale up --force-reauth

Key Rotation¶

Device keys automatically rotate. Manual rotation:

Remove device from admin console
Re-authenticate: sudo tailscale up

Best Practices¶

Auth Keys¶

Use short expiration for one-time keys
Use ephemeral for temporary workloads
Tag at key creation for consistent tagging
Rotate regularly for long-lived deployments
Don't commit to git - use secrets management

API Keys¶

Minimum scopes - only what's needed
Short expiration when possible
Separate keys for different services
Audit usage - who uses which key
Rotate compromised keys immediately

Secrets Management¶

Environment Variables¶

# Never hardcode
export TS_AUTHKEY=tskey-auth-xxxxx
sudo tailscale up --auth-key=$TS_AUTHKEY

CI/CD Secrets¶

# GitHub Actions
- name: Setup Tailscale
  env:
    TS_AUTHKEY: ${{ secrets.TAILSCALE_AUTHKEY }}
  run: |
    tailscale up --auth-key=$TS_AUTHKEY

Kubernetes Secrets¶

apiVersion: v1
kind: Secret
metadata:
  name: tailscale-auth
type: Opaque
stringData:
  authkey: tskey-auth-xxxxx

HashiCorp Vault¶

# Store
vault kv put secret/tailscale authkey=tskey-auth-xxxxx

# Retrieve
export TS_AUTHKEY=$(vault kv get -field=authkey secret/tailscale)

Revoking Keys¶

Auth Keys¶

Settings → Keys
Find key → Revoke
Existing devices stay connected
New registrations fail

API Keys¶

Settings → Keys
Find API key → Revoke
API calls with key fail immediately

Device Keys¶

Machines → Select device
Remove or Expire key
Device disconnects

Monitoring Key Usage¶

Admin Console¶

View active auth keys
See which devices used which key
Monitor API key usage

Audit Logs¶

Enterprise plans show: - Key creation/revocation events - API calls per key - Authentication attempts