Contacts
get
contacts.get
Get the tailnet’s account, support and security contact emails.
Risk: read
account full type
account full type
support full type
support full type
security full type
security full type
resendVerificationEmail
contacts.resendVerificationEmail
Email the verification link for a contact address again.
Risk: destructive
update
contacts.update
Change the account, support or security contact email. Tailscale emails the new address to verify it.
Risk: destructive
Device Invites
accept
deviceInvites.accept
Accept a device share invite from another tailnet into this key’s tailnet, by its invite URL or code. The shared device then appears in devices.list. Needs a user’s API access token: a share belongs to a user, so an OAuth client can’t accept one.
Risk: write
device full type
device full type
acceptedBy full type
acceptedBy full type
create
deviceInvites.create
Share a device with people outside the tailnet. Each invite gives an invite URL to send; with email set, Tailscale emails the invite itself. allowExitNode lets the recipient use the device as an exit node; multiUse lets several people accept one link. deviceId is the device id or nodeId from devices.list.
Risk: destructive
invites full type
invites full type
object[] \| null
Output full type
Output full type
delete
deviceInvites.delete
Delete a device share invite; its link stops working.
Risk: write
get
deviceInvites.get
Get a device share invite: its invite URL, who accepted it and when.
Risk: read
acceptedBy full type
acceptedBy full type
list
deviceInvites.list
List the share invites for a device (who it was shared with, accepted or not); null when there are none. deviceId is the device id or nodeId from devices.list.
Risk: read
object[] \| null
Output full type
Output full type
resend
deviceInvites.resend
Email a device share invite again to the address it was created for.
Risk: destructive
Devices
authorize
devices.authorize
Approve (authorized: true) or revoke approval for (authorized: false) a device when the tailnet requires device approval. Revoking cuts the device’s access until it is approved again. deviceId is the device id or nodeId from devices.list.
Risk: write
delete
devices.delete
Remove a device from the tailnet. It loses access at once and must be signed in again (with a new auth key or login) to rejoin. Cannot be undone. deviceId is the device id or nodeId from devices.list.
Risk: destructive · Irreversible
expireKey
devices.expireKey
Expire a device’s node key now: the device is disconnected until someone signs in on it again. Use it to cut off a lost or compromised machine. deviceId is the device id or nodeId from devices.list.
Risk: destructive
get
devices.get
Get one device. fields: “all” adds routes, posture and connectivity details. deviceId is the device id or nodeId from devices.list.
Risk: read
clientConnectivity full type
clientConnectivity full type
postureIdentity full type
postureIdentity full type
postureStatus full type
postureStatus full type
distro full type
distro full type
list
devices.list
List the devices in the tailnet: name, hostname, Tailscale IPs, owner, OS, client version, tags, last seen, key expiry, authorized. Pass fields: “all” to add advertised and enabled routes, posture and connectivity details. filters narrows the list on the server by exact match on top-level device fields, all of them required to match (for example { tags: [“tag:prod”], isEphemeral: true }).
Risk: read
devices full type
devices full type
postureAttributes.batchUpdate
devices.postureAttributes.batchUpdate
Set or delete custom posture attributes on many devices in one call. A null value deletes that attribute. Applied all together or not at all.
Risk: write
nodes full type
nodes full type
postureAttributes.delete
devices.postureAttributes.delete
Delete a custom posture attribute (custom:…) from a device. deviceId is the device id or nodeId from devices.list.
Risk: write
postureAttributes.get
devices.postureAttributes.get
Get a device’s posture attributes: Tailscale’s own (node:os, node:tsVersion, node:tsReleaseTrack, …) and custom ones (custom:<name>) set through the API or a posture integration. deviceId is the device id or nodeId from devices.list.
Risk: read
postureAttributes.set
devices.postureAttributes.set
Set a custom posture attribute on a device. attributeKey must start with custom: (for example custom:agentApproved); value is a string, number or boolean. expiry (RFC 3339) makes it lapse on its own. Policy postures can then allow or deny access on it. deviceId is the device id or nodeId from devices.list.
Risk: write
routes.list
devices.routes.list
List the subnet routes and exit-node routes a device advertises and which of them are enabled. deviceId is the device id or nodeId from devices.list.
Risk: read
routes.set
devices.routes.set
Set which of the routes a device advertises are enabled (subnet routes, and 0.0.0.0/0 plus ::/0 for an exit node). Replaces the enabled list: routes left out are turned off. Only routes the device advertises can be enabled. deviceId is the device id or nodeId from devices.list.
Risk: write
setIp
devices.setIp
Change a device’s Tailscale IPv4 address to an unused one in the tailnet’s range (100.64.0.0/10 by default). Existing connections to the old address break and must reconnect to the new one. deviceId is the device id or nodeId from devices.list.
Risk: write
setName
devices.setName
Rename a device: its MagicDNS name becomes <name>.<tailnet>.ts.net. Pass name: "" to go back to the machine’s own hostname. Connections using the old name stop resolving. deviceId is the device id or nodeId from devices.list.
Risk: write
setTags
devices.setTags
Replace a device’s ACL tags (tag:server, tag:mcp, …). Each tag must be defined in the policy file and owned by the caller (tagOwners). Tagging a user’s device turns it into a tagged device that no longer belongs to that user, and the access rules for its tags apply from then on. Pass tags: [] to remove every tag. deviceId is the device id or nodeId from devices.list.
Risk: write
updateKey
devices.updateKey
Turn key expiry off (keyExpiryDisabled: true) or back on for a device, for servers that should stay signed in. deviceId is the device id or nodeId from devices.list.
Risk: write
Dns
configuration.get
dns.configuration.get
Get the tailnet’s whole DNS configuration in one object: nameservers, split DNS, search paths and preferences.
Risk: read
nameservers full type
nameservers full type
splitDNS full type
splitDNS full type
preferences full type
preferences full type
configuration.set
dns.configuration.set
Replace the tailnet’s whole DNS configuration in one call (nameservers, split DNS, search paths, preferences).
Risk: write
nameservers full type
nameservers full type
splitDNS full type
splitDNS full type
preferences full type
preferences full type
nameservers full type
nameservers full type
splitDNS full type
splitDNS full type
preferences full type
preferences full type
nameservers.list
dns.nameservers.list
List the global DNS nameservers devices use.
Risk: read
nameservers.set
dns.nameservers.set
Replace the global DNS nameservers (IP addresses). An empty list removes them all and turns MagicDNS off.
Risk: write
preferences.get
dns.preferences.get
Get whether MagicDNS is on.
Risk: read
preferences.set
dns.preferences.set
Turn MagicDNS on or off. Turning it on needs at least one nameserver; turning it off breaks <name>.ts.net lookups.
Risk: write
searchPaths.list
dns.searchPaths.list
List the DNS search domains pushed to devices.
Risk: read
searchPaths.set
dns.searchPaths.set
Replace the DNS search domains pushed to devices.
Risk: write
splitDns.get
dns.splitDns.get
Get split DNS: which nameservers answer for which domains.
Risk: read
Record<string, string[] \| null>
splitDns.set
dns.splitDns.set
Replace the whole split DNS map (domain to nameservers). Domains left out are removed.
Risk: write
Record<string, string[] \| null>
splitDns.update
dns.splitDns.update
Change split DNS for the given domains only; a domain set to null is removed, others are kept.
Risk: write
Record<string, string[] \| null>
Keys
create
keys.create
Create an auth key (keyType “auth”, the default) that adds a device to the tailnet, or a trust credential (keyType “client” for an OAuth client, “federated” for a federated identity). For an agent or server, make the auth key preauthorized, tagged (capabilities.devices.create.tags) and ephemeral so the node is removed when it goes offline. The secret is returned once in key: hand it to the machine right away, never paste it into chat.
Risk: destructive
capabilities full type
capabilities full type
capabilities full type
capabilities full type
delete
keys.delete
Revoke a key. Devices already added with an auth key stay; anything using a revoked API token or OAuth client stops working. Cannot be undone.
Risk: destructive · Irreversible
get
keys.get
Get a key: type, description, scopes, tags, created, expires, revoked. Never returns the secret.
Risk: read
capabilities full type
capabilities full type
list
keys.list
List the keys of the caller (all: true for every key in the tailnet): auth keys, API access tokens, OAuth clients and federated identities, with expiry, scopes and tags. Never returns the secrets.
Risk: read
keys full type
keys full type
update
keys.update
Change an OAuth client’s or federated identity’s description, scopes or tags (auth keys and API tokens can’t be edited).
Risk: write
capabilities full type
capabilities full type
Logging
awsExternalId.get
logging.awsExternalId.get
Get (or create on first use) the AWS external ID to put in an IAM role trust policy before streaming logs to S3.
Risk: write
awsExternalId.validate
logging.awsExternalId.validate
Check that an IAM role trusts Tailscale with this external ID, before log streaming to S3 is turned on.
Risk: read
configurationLogs.list
logging.configurationLogs.list
Read the configuration audit log between start and end (RFC 3339): who changed the policy file, approved or deleted a device, created a key, changed a setting, with old and new values. Filter by actor, target or event (TAILNET.UPDATE.ACL, NODE.CREATE, NODE.APPROVE, API_KEY.CREATE, USER.UPDATE.USER_ROLE, …). Use it to answer “who changed what, and when”.
Risk: read
logs full type
logs full type
networkLogs.list
logging.networkLogs.list
Read network flow logs between start and end (RFC 3339): which device talked to which, over what protocol and ports, and how many bytes. Network flow logging must be turned on (Premium and Enterprise plans).
Risk: read
logs full type
logs full type
streaming.disable
logging.streaming.disable
Stop streaming configuration or network logs; the destination settings are removed.
Risk: destructive
streaming.get
logging.streaming.get
Get where configuration or network logs are streamed (Splunk, Elastic, Panther, Cribl, CrowdStrike, Datadog, Axiom or S3).
Risk: read
streaming.getStatus
logging.streaming.getStatus
Get whether log streaming to a SIEM is working for configuration or network logs, and its last errors.
Risk: read
streaming.set
logging.streaming.set
Start or change streaming of configuration or network logs to a SIEM or bucket. Replaces the current destination.
Risk: write
Oauth Apps
create
oauthApps.create
Register an OAuth app in the tailnet with its redirect URIs and scopes. The client secret is returned once.
Risk: destructive
delete
oauthApps.delete
Delete an OAuth app; sign-ins and tokens issued through it stop working.
Risk: destructive · Irreversible
get
oauthApps.get
Get an OAuth app: name, redirect URIs, scopes. Never returns the secret.
Risk: read
list
oauthApps.list
List the OAuth apps registered in the tailnet (apps people in the tailnet sign in to so it can act on their behalf).
Risk: read
oauthApps full type
oauthApps full type
update
oauthApps.update
Replace an OAuth app’s name, redirect URIs or scopes.
Risk: write
Policy File
get
policyFile.get
Get the tailnet’s policy file (ACLs or grants, groups, tagOwners, autoApprovers, postures, tests). format “hujson” (the default) keeps comments and returns the text; “json” returns an object without comments. etag is the version: pass it as ifMatch to policyFile.set so another edit made in between is not overwritten. details: true also returns warnings and errors.
Risk: read
policy full type
policy full type
preview
policyFile.preview
Show which rules of the policy file you pass apply to a user (type “user”, previewFor their email) or a destination (type “ipport”, previewFor “100.101.102.103:443”), without saving anything. policy is required: pass a draft, or the text from policyFile.get to preview the current file.
Risk: read
policy full type
policy full type
matches full type
matches full type
set
policyFile.set
Replace the tailnet’s policy file, as HuJSON text (keeps comments) or a JSON object. It controls who can reach what across the whole tailnet, so run policyFile.validate first, and pass ifMatch with the etag from policyFile.get: Tailscale then refuses the write if the file changed since. Tests in the file must pass or nothing is saved.
Risk: destructive
policy full type
policy full type
policy full type
policy full type
validate
policyFile.validate
Check a draft policy file without saving it: pass policy (HuJSON text or object) to parse it and run its tests, or tests (at least one) to run ACL tests against the current file. null or an empty message means everything passed. Problems still answer 200: message holds the parse error, or “test(s) failed” with each failing test in data.
Risk: read
policy full type
policy full type
tests full type
tests full type
data full type
data full type
Posture Integrations
create
postureIntegrations.create
Connect a device posture provider, so its attributes (compliance, risk score) can gate access in the policy file.
Risk: write
status full type
status full type
delete
postureIntegrations.delete
Disconnect a device posture provider; rules that rely on its attributes stop matching.
Risk: destructive · Irreversible
get
postureIntegrations.get
Get a device posture integration and its sync status.
Risk: read
status full type
status full type
list
postureIntegrations.list
List device posture integrations (CrowdStrike Falcon, Intune, Jamf Pro, Kandji, Kolide, SentinelOne, …).
Risk: read
integrations full type
integrations full type
update
postureIntegrations.update
Change a device posture integration (credentials, tenant, which devices it reads).
Risk: write
status full type
status full type
Services
delete
services.delete
Delete a Tailscale Service; its address stops answering on every host.
Risk: destructive · Irreversible
get
services.get
Get a Tailscale Service: its addresses, ports, tags and comment. serviceName is svc:<name>.
Risk: read
hosts.getApproval
services.hosts.getApproval
Get whether a device is approved to serve a Tailscale Service.
Risk: read
hosts.list
services.hosts.list
List the devices that advertise a Tailscale Service and whether each is approved to serve it.
Risk: read
hosts full type
hosts full type
hosts.setApproval
services.hosts.setApproval
Approve (approved: true) or stop (false) a device serving a Tailscale Service, when its tags are not auto-approved.
Risk: write
list
services.list
List Tailscale Services: named virtual endpoints (svc:<name>) with their own Tailscale IPs and MagicDNS name, served by one or more hosts. Use them to give an internal app or MCP server a stable address on the tailnet.
Risk: read
vipServices full type
vipServices full type
update
services.update
Create or replace a Tailscale Service (serviceName svc:<name>; name defaults to it): ports (“tcp:443”, “do-not-validate”) and tags. Hosts then advertise it with tailscale serve --service=svc:<name>, and the policy file grants who may reach it.
Risk: write
Tailnets
create
tailnets.create
Create an API-only tailnet in the organization (no human users, not in the admin console), for an app or agent fleet that manages its own network. At most 10 tailnets per organization. The new OAuth client secret is returned once.
Risk: destructive
oauthClient full type
oauthClient full type
delete
tailnets.delete
Delete a whole tailnet with all of its users, devices and settings. Only API-only tailnets can be deleted this way. Cannot be undone.
Risk: destructive · Irreversible
list
tailnets.list
List the tailnets in the organization: the original one and any API-only tailnets made with tailnets.create. Pages with cursor.
Risk: read
tailnets full type
tailnets full type
Tailnet Settings
get
tailnetSettings.get
Get tailnet settings: device and user approval, device auto-updates, key expiry days, who may join, posture identity collection, network flow logging, regional routing, HTTPS.
Risk: read
update
tailnetSettings.update
Change tailnet settings; only the fields sent change. Turning on device approval holds every new device until someone approves it. Tailscale answers without the new values: read them with tailnetSettings.get.
Risk: write
User Invites
create
userInvites.create
Invite people to join the tailnet with a role (member, admin, …). Each invite gives an invite URL; with email set, Tailscale emails it. Needs a user’s API access token (an invite needs an inviting user), not an OAuth client.
Risk: destructive
invites full type
invites full type
object[] \| null
Output full type
Output full type
delete
userInvites.delete
Delete an invite to join the tailnet; its link stops working. Needs a user’s API access token.
Risk: write
get
userInvites.get
Get an invite to join the tailnet: role, invite URL, email and whether it was accepted.
Risk: read
list
userInvites.list
List pending invites for people to join the tailnet; null when there are none. Invites need a user’s API access token, not an OAuth client.
Risk: read
object[] \| null
Output full type
Output full type
resend
userInvites.resend
Email an invite to join the tailnet again.
Risk: destructive
Users
approve
users.approve
Approve a user waiting for approval (when the tailnet requires user approval).
Risk: write
delete
users.delete
Delete a user from the tailnet, with their devices. Cannot be undone; users.suspend keeps them restorable. A user’s own token can’t delete that user.
Risk: destructive · Irreversible
get
users.get
Get one user: role, status, login name, device count, last seen.
Risk: read
list
users.list
List users: role, status (active, idle, suspended, needs-approval), device count, last seen. type and role filter the list.
Risk: read
users full type
users full type
restore
users.restore
Restore a suspended user and their access.
Risk: write
suspend
users.suspend
Suspend a user: they lose access to the tailnet until restored; their devices and settings are kept. A user’s own token can’t suspend that user.
Risk: write
updateRole
users.updateRole
Change a user’s role (member, admin, it-admin, network-admin, billing-admin, auditor, owner).
Risk: write
Webhooks
create
webhooks.create
Add a webhook endpoint for tailnet events (nodeCreated, nodeNeedsApproval, nodeKeyExpiringInOneDay, nodeDeleted, policyUpdate, userNeedsApproval, userRoleUpdated, …), or a whole category (categoryTailnetManagement, categoryDeviceMisconfigurations) that also takes events Tailscale adds later. Tailscale signs each event with the secret (Tailscale-Webhook-Signature). providerType “slack”, “discord”, “mattermost” or “googlechat” formats the message for that chat app; "" or none sends the generic format. The signing secret is returned once: keep it to verify events.
Risk: write
delete
webhooks.delete
Delete a webhook endpoint; Tailscale stops sending it events.
Risk: destructive · Irreversible
get
webhooks.get
Get a webhook endpoint: URL, provider type and subscribed events.
Risk: read
list
webhooks.list
List the webhook endpoints that receive tailnet events (device added, needs approval, policy changed, user joined, …).
Risk: read
webhooks full type
webhooks full type
rotateSecret
webhooks.rotateSecret
Replace a webhook endpoint’s signing secret. The new one is returned once; signatures made with the old one stop verifying.
Risk: destructive · Irreversible
test
webhooks.test
Send a test event to a webhook endpoint (a chat channel, for a Slack or Discord one) to check it receives and accepts deliveries.
Risk: destructive
update
webhooks.update
Change which events a webhook endpoint receives.
Risk: write