Tailscale Devices & Users
Which laptops have not checked in for a month, and who is still waiting for approval? Audit your tailnet: list devices with last-seen times, OS and tags, review users and pending invites, read the ACL policy, and approve, rename or re-tag a device.
Connect this API to an AI agent Browse all specs
What you can do with Tailscale Devices & Users via MCP
Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.
| Method | Path | Operation | Description |
|---|---|---|---|
| GET | /tailnet/{tailnet}/devices |
listDevices | List devices with OS, addresses, tags and last-seen time |
| GET | /device/{deviceId} |
getDevice | Get one device's details |
| POST | /device/{deviceId}/authorized |
authorizeDevice | Approve (or de-authorize) a device waiting for approval |
| POST | /device/{deviceId}/name |
setDeviceName | Rename a device (its MagicDNS name) |
| POST | /device/{deviceId}/tags |
setDeviceTags | Replace a device's ACL tags |
| GET | /device/{deviceId}/routes |
listDeviceRoutes | List subnet routes a device advertises and which are enabled |
| GET | /tailnet/{tailnet}/users |
listUsers | List users with role, status and last-seen time |
| GET | /users/{userId} |
getUser | Get one user's details |
| GET | /tailnet/{tailnet}/user-invites |
listUserInvites | List pending user invites |
| GET | /tailnet/{tailnet}/keys |
listAuthKeys | List auth keys and API tokens (metadata only) |
| GET | /tailnet/{tailnet}/acl |
getPolicyFile | Read the tailnet policy file (ACLs, groups, tag owners) |
Authentication
bearerAuth
Bearer token — sent as Authorization: Bearer <token>
Tailscale API access token sent as Authorization: Bearer tskey-api-....
How to get a credential
- Open the Tailscale admin console > Settings > Keys (login.tailscale.com/admin/settings/keys).
- Under API access tokens, click Generate access token, set an expiry (1-90 days) and copy the
tskey-api-...value. - For a long-lived integration, create an OAuth client (Settings > OAuth clients) with the scopes below and exchange it for a token instead.
Permissions used
API access tokens carry the full permissions of the user who created them (Admin, IT admin or Network admin needed for writes). OAuth client scopes:
| Scope | Operations |
|---|---|
devices:core:read |
listDevices, getDevice |
devices:core |
authorizeDevice, setDeviceName, setDeviceTags |
devices:routes:read |
listDeviceRoutes |
users:read |
listUsers, getUser |
auth_keys:read (add api_access_tokens:read, oauth_keys:read to see those key types) |
listAuthKeys |
| none listed (use an API access token) | listUserInvites |
policy_file:read |
getPolicyFile |
Common errors
- 401 Unauthorized: token missing, mistyped or expired (tokens last at most 90 days). Generate a new one.
- 403 Forbidden: the token's user role or OAuth scope does not allow this call, e.g. setting tags you do not own.
- 400 Bad Request: invalid body, e.g. a tag not defined under
tagOwnersin the policy file or not prefixedtag:. - 404 Not Found: wrong device id or tailnet name; use
-for the token's own tailnet. - 429 Too Many Requests: back off and retry after a few seconds.
Store the token as a VX Agents credential so it is never pasted into chat.
Usage guide
Setup
- Add a Bearer credential: a Tailscale API access token (
tskey-api-..., Admin console > Settings > Keys). Tokens expire after 1-90 days; renew the credential before then. - Preset
tailnetto-(the token's own tailnet) unless you manage several tailnets; then use the Tailnet ID from Settings > General.
Audit the tailnet
listDeviceswithtailnet=-(addfields=allfor routes and posture details). Each device hasid(usenodeId),name,hostname,os,user,tags,addresses,lastSeen,authorized,keyExpiryDisabledandexpires.- Flag stale devices (old
lastSeen), keys about to expire (expires) and devices withauthorized: false. getDevicefor one device;listDeviceRoutesto see advertised vs enabled subnet routes.listUsers(filterrole, e.g.admin, ortype=shared) for status, role andlastSeen;getUserfor one user.listUserInvitesshows invites not yet accepted.listAuthKeysto review which auth keys and API tokens exist and when they expire (secrets are never returned).getPolicyFileto read ACLs, groups andtagOwnersbefore changing tags.
Change a device
Show the user the device and the change and wait for confirmation, then:
- Approve:
authorizeDevicewith{"authorized": true}(falseremoves access immediately). - Rename:
setDeviceNamewith{"name": "build-runner-1"}. - Re-tag:
setDeviceTagswith{"tags": ["tag:server", "tag:prod"]}. This replaces all tags, and each tag must be intagOwners.
Good to know
- Device ids: prefer
nodeId(e.g.nXXXXXCNTRL); the numericidalso works. - Times are RFC 3339 UTC.
- De-authorizing or re-tagging a device can cut it off from the network or change what it can reach: double-check with the user.
- This spec cannot delete devices or users, create keys or edit the policy file.
Source: Tailscale API reference (https://tailscale.com/api), checked 2026-10-21.
How to use this spec
- Create a free VX Agents account (sandbox tools included).
- Open the marketplace and connect “Tailscale Devices & Users” to an agent.
- Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.