Skip to main content
New to Corsair? See API access, authentication, and error handling.

Contacts

get

contacts.get Get the tailnet’s account, support and security contact emails. Risk: read
Input Output

resendVerificationEmail

contacts.resendVerificationEmail Email the verification link for a contact address again. Risk: destructive
Input Output

update

contacts.update Change the account, support or security contact email. Tailscale emails the new address to verify it. Risk: destructive
Input Output

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
Input Output

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
Input
Output: object[] \| null

delete

deviceInvites.delete Delete a device share invite; its link stops working. Risk: write
Input Output

get

deviceInvites.get Get a device share invite: its invite URL, who accepted it and when. Risk: read
Input Output

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
Input Output: object[] \| null

resend

deviceInvites.resend Email a device share invite again to the address it was created for. Risk: destructive
Input Output

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
Input Output

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
Input Output

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
Input Output

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
Input Output

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
Input Output

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
Input
Output

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
Input Output

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
Input Output

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
Input Output

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
Input Output

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
Input Output

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
Input Output

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
Input Output

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
Input Output

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
Input Output

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
Input Output

configuration.set

dns.configuration.set Replace the tailnet’s whole DNS configuration in one call (nameservers, split DNS, search paths, preferences). Risk: write
Input
Output

nameservers.list

dns.nameservers.list List the global DNS nameservers devices use. Risk: read
Input Output

nameservers.set

dns.nameservers.set Replace the global DNS nameservers (IP addresses). An empty list removes them all and turns MagicDNS off. Risk: write
Input Output

preferences.get

dns.preferences.get Get whether MagicDNS is on. Risk: read
Input Output

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
Input Output

searchPaths.list

dns.searchPaths.list List the DNS search domains pushed to devices. Risk: read
Input Output

searchPaths.set

dns.searchPaths.set Replace the DNS search domains pushed to devices. Risk: write
Input Output

splitDns.get

dns.splitDns.get Get split DNS: which nameservers answer for which domains. Risk: read
Input Output: 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
Input Output: 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
Input Output: 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
Input
Output

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
Input Output

get

keys.get Get a key: type, description, scopes, tags, created, expires, revoked. Never returns the secret. Risk: read
Input Output

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
Input Output

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
Input Output

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
Input Output

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
Input Output

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
Input Output

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
Input Output

streaming.disable

logging.streaming.disable Stop streaming configuration or network logs; the destination settings are removed. Risk: destructive
Input Output

streaming.get

logging.streaming.get Get where configuration or network logs are streamed (Splunk, Elastic, Panther, Cribl, CrowdStrike, Datadog, Axiom or S3). Risk: read
Input Output

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
Input Output

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
Input Output

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
Input Output

delete

oauthApps.delete Delete an OAuth app; sign-ins and tokens issued through it stop working. Risk: destructive · Irreversible
Input Output

get

oauthApps.get Get an OAuth app: name, redirect URIs, scopes. Never returns the secret. Risk: read
Input Output

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
Input Output

update

oauthApps.update Replace an OAuth app’s name, redirect URIs or scopes. Risk: write
Input Output

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
Input Output

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
Input
Output

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
Input
Output

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
Input
Output

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
Input Output

delete

postureIntegrations.delete Disconnect a device posture provider; rules that rely on its attributes stop matching. Risk: destructive · Irreversible
Input Output

get

postureIntegrations.get Get a device posture integration and its sync status. Risk: read
Input Output

list

postureIntegrations.list List device posture integrations (CrowdStrike Falcon, Intune, Jamf Pro, Kandji, Kolide, SentinelOne, …). Risk: read
Input Output

update

postureIntegrations.update Change a device posture integration (credentials, tenant, which devices it reads). Risk: write
Input Output

Services

delete

services.delete Delete a Tailscale Service; its address stops answering on every host. Risk: destructive · Irreversible
Input Output

get

services.get Get a Tailscale Service: its addresses, ports, tags and comment. serviceName is svc:<name>. Risk: read
Input Output

hosts.getApproval

services.hosts.getApproval Get whether a device is approved to serve a Tailscale Service. Risk: read
Input Output

hosts.list

services.hosts.list List the devices that advertise a Tailscale Service and whether each is approved to serve it. Risk: read
Input Output

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
Input Output

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
Input Output

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
Input Output

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
Input Output

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
Input Output

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
Input Output

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
Input Output

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
Input Output

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
Input
Output: object[] \| null

delete

userInvites.delete Delete an invite to join the tailnet; its link stops working. Needs a user’s API access token. Risk: write
Input Output

get

userInvites.get Get an invite to join the tailnet: role, invite URL, email and whether it was accepted. Risk: read
Input Output

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
Input Output: object[] \| null

resend

userInvites.resend Email an invite to join the tailnet again. Risk: destructive
Input Output

Users

approve

users.approve Approve a user waiting for approval (when the tailnet requires user approval). Risk: write
Input Output

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
Input Output

get

users.get Get one user: role, status, login name, device count, last seen. Risk: read
Input Output

list

users.list List users: role, status (active, idle, suspended, needs-approval), device count, last seen. type and role filter the list. Risk: read
Input Output

restore

users.restore Restore a suspended user and their access. Risk: write
Input Output

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
Input Output

updateRole

users.updateRole Change a user’s role (member, admin, it-admin, network-admin, billing-admin, auditor, owner). Risk: write
Input Output

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
Input Output

delete

webhooks.delete Delete a webhook endpoint; Tailscale stops sending it events. Risk: destructive · Irreversible
Input Output

get

webhooks.get Get a webhook endpoint: URL, provider type and subscribed events. Risk: read
Input Output

list

webhooks.list List the webhook endpoints that receive tailnet events (device added, needs approval, policy changed, user joined, …). Risk: read
Input Output

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
Input Output

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
Input Output

update

webhooks.update Change which events a webhook endpoint receives. Risk: write
Input Output