Tailscale

Tailscale

This connector manages a Tailscale network (tailnet) through the Tailscale API v2 (https://api.tailscale.com/api/v2): devices and their routes, tags and approval, users, auth keys, the policy file (access rules), DNS, tailnet settings, configuration audit logs and network flow logs, log streaming, webhooks, Tailscale Services and posture integrations. Every call goes to the tailnet that owns the OAuth client (- in the path).

Setup (5 minutes, tailnet Owner, Admin, Network admin or IT admin)

1. Open https://login.tailscale.com/admin/settings/trust-credentials (Settings, Trust credentials; older consoles: Settings, OAuth clients) and click Credential, then OAuth.
2. Pick the scopes. For reading only, all:read is enough. For the write tools add the matching write scopes: devices:core (needs one or more tags, e.g. tag:server), devices:routes, users, auth_keys (also needs tags), policy_file, dns, feature_settings, webhooks. all grants everything.
3. Copy the Client ID into TAILSCALE_OAUTH_CLIENT_ID and the Client secret (tskey-client-..., shown once) into TAILSCALE_OAUTH_CLIENT_SECRET.
4. Install. The connector exchanges the client for a one-hour access token at /api/v2/oauth/token and renews it by itself. Unlike API access tokens (at most 90 days), an OAuth client does not expire, so the connector keeps working. A write the client has no scope for answers 403.

Secrets: read this before using the keys and webhook tools. The AI sees whatever a tool returns. tailscale_create_auth_key returns a new auth key (tskey-auth-...) and tailscale_create_webhook a webhook signing secret, each shown only once; both end up in the conversation and in the AI provider's context. Pass them only to the person who asked, never into other tools, files or messages. tailscale_list_user_invites shows invite links that let anyone join. tailscale_list_keys and tailscale_get_key never return key values, and tailscale_list_webhooks, tailscale_get_webhook and tailscale_get_log_streaming_configuration have secrets, tokens and cloud credentials removed. The connector cannot create OAuth clients or API tokens.

Workflow

• Devices: tailscale_list_devices (filter with filter, e.g. hostname=web-1, tags=tag:prod, authorized=false; fields=all adds routes and connectivity), tailscale_get_device, tailscale_get_device_routes, tailscale_get_device_posture_attributes. Changes: tailscale_authorize_device (device approval), tailscale_set_device_routes (approve subnet routes and exit nodes), tailscale_set_device_tags, tailscale_set_device_name, tailscale_set_device_key_expiry, tailscale_expire_device_key, tailscale_delete_device.
• Users: tailscale_list_users (by role or type), tailscale_get_user, tailscale_list_user_invites; tailscale_update_user_role, tailscale_approve_user, tailscale_suspend_user and tailscale_restore_user (a suspension is undone by restoring), tailscale_delete_user.
• Keys: tailscale_list_keys (all=true for auth keys and API tokens too), tailscale_get_key, tailscale_create_auth_key to add servers, containers or CI runners, tailscale_delete_key to revoke one.
• Access rules: tailscale_get_policy_file to read, tailscale_preview_policy_rules to see which rules hit a user or an IP:port, tailscale_validate_policy_file to check a draft and run its tests (both change nothing), then tailscale_set_policy_file with the etag from the read.
• DNS: tailscale_get_dns_configuration shows everything; change it with tailscale_set_dns_nameservers, tailscale_set_dns_preferences (MagicDNS), tailscale_set_dns_search_paths and tailscale_update_split_dns.
• Tailnet: tailscale_get_tailnet_settings, tailscale_update_tailnet_settings, tailscale_get_contacts.
• Logs and audit: tailscale_list_configuration_audit_logs (who changed what), tailscale_list_network_flow_logs (traffic, Premium and Enterprise), tailscale_get_log_streaming_status and tailscale_get_log_streaming_configuration for SIEM streaming.
• Webhooks, Services, posture: tailscale_list_webhooks, tailscale_get_webhook, tailscale_create_webhook; tailscale_list_services, tailscale_get_service, tailscale_list_service_hosts; tailscale_list_posture_integrations.

Switched off at install: tailscale_expire_device_key, tailscale_delete_device, tailscale_delete_user, tailscale_delete_key; they cannot be undone, so an admin switches them on when the team needs them. tailscale_set_policy_file is switched off as well: it replaces the whole access policy of the tailnet in one call, and a wrong rule cuts users and devices off, so an admin switches it on deliberately.

Reading the answers: device nodeId (e.g. nAbCdEf1CNTRL) is the preferred device id, the numeric id also works. name is the MagicDNS name (web-1.tailnet-name.ts.net), addresses the Tailscale IPs (100.x.y.z and fd7a:115c:a1e0::/48). Times are RFC 3339 in UTC; lastSeen is empty while a device is connected (connectedToControl: true). expires of 0001-01-01 means key expiry is off. Tags look like tag:name. Lists come in one answer without paging.

Changes replace lists: routes, tags, nameservers and search paths are sent as the complete list. Read the current value first, then send old plus new.

Errors: 401 the OAuth client was deleted or the secret is wrong; 403 the client lacks the scope (or the tags) for this call, or the plan lacks the feature; 404 the id does not exist in this tailnet; 400 with message for invalid input, policy files with failing tests included; 412 the policy changed since your etag; 429 rate limited, wait and retry.