API Documentation
General
Enterprise
- GETGet appearance
- PUTUpdate appearance
- POSTIssue signed app token for reconnecting PTY
- GETGet entitlements
- GETGet groups
- GETGet group by ID
- DELDelete group by name
- PATCHUpdate group by name
- GETGet JFrog XRay scan by workspace agent ID.
- POSTPost JFrog XRay scan by workspace agent ID.
- GETGet licenses
- DELDelete license
- PUTUpdate notification template dispatch method
- GETGet OAuth2 applications.
- POSTCreate OAuth2 application.
- GETGet OAuth2 application.
- PUTUpdate OAuth2 application.
- DELDelete OAuth2 application.
- GETGet OAuth2 application secrets.
- POSTCreate OAuth2 application secret.
- DELDelete OAuth2 application secret.
- POSTOAuth2 authorization request.
- POSTOAuth2 token exchange.
- DELDelete OAuth2 application tokens.
- GETGet groups by organization
- POSTCreate group for organization
- GETGet group by organization and group name
- GETGet workspace quota by user
- GETGet provisioner daemons
- GETServe provisioner daemon
- GETList provisioner key
- POSTCreate provisioner key
- GETList provisioner key daemons
- DELDelete provisioner key
- GETGet the available organization idp sync claim fields
- GETGet group IdP Sync settings by organization
- PATCHUpdate group IdP Sync settings by organization
- GETGet role IdP Sync settings by organization
- PATCHUpdate role IdP Sync settings by organization
- GETGet active replicas
- GETSCIM 2.0: Service Provider Config
- GETSCIM 2.0: Get users
- POSTSCIM 2.0: Create new user
- GETSCIM 2.0: Get user by ID
- PATCHSCIM 2.0: Update user account
- GETGet organization IdP Sync settings
- PATCHUpdate organization IdP Sync settings
- GETGet template ACLs
- PATCHUpdate template ACL
- GETGet template available acl users/groups
- GETGet user quiet hours schedule
- PUTUpdate user quiet hours schedule
- GETGet workspace quota by user deprecated
- GETGet workspace proxies
- POSTCreate workspace proxy
- POSTReport workspace app stats
- GETWorkspace Proxy Coordinate
- GETGet workspace proxy crypto keys
- POSTDeregister workspace proxy
- POSTIssue signed workspace app token
- POSTRegister workspace proxy
- GETGet workspace proxy
- DELDelete workspace proxy
- PATCHUpdate workspace proxy
Authorization
Debug
Agents
- GETDebug OIDC context for a user
- GETGet DERP map updates
- GETUser-scoped tailnet RPC connection
- POSTAuthenticate agent on AWS instance
- POSTAuthenticate agent on Azure instance
- GETGet connection info for workspace agent generic
- POSTAuthenticate agent on Google Cloud instance
- GETGet workspace agent external auth
- GETRemoved: Get workspace agent git auth
- GETGet workspace agent Git SSH key
- POSTPost workspace agent log source
- PATCHPatch workspace agent logs
- GETWorkspace agent RPC API
- GETGet workspace agent by ID
- GETGet connection info for workspace agent
- GETCoordinate workspace agent
- GETGet listening ports for workspace agent
- GETGet logs by workspace agent
- GETOpen PTY to workspace agent
- GETRemoved: Get logs by workspace agent
- GETWatch for workspace agent metadata updates
Git
Insights
Organizations
Notifications
Members
Workspaces
- POSTCreate user workspace by organization
- GETGet workspace metadata by user and workspace name
- POSTCreate user workspace
- GETList workspaces
- GETGet workspace metadata by ID
- PATCHUpdate workspace metadata by ID
- PUTUpdate workspace autostart schedule by ID
- PUTUpdate workspace automatic updates by ID
- PUTUpdate workspace dormancy status by id.
- PUTExtend workspace deadline by ID
- PUTFavorite workspace by ID.
- DELUnfavorite workspace by ID.
- GETResolve workspace autostart by id.
- GETGet workspace timings by ID
- PUTUpdate workspace TTL by ID
- POSTPost Workspace Usage by ID
- GETWatch workspace by ID
Templates
- GETGet templates by organization
- POSTCreate template by organization
- GETGet template examples by organization
- GETGet templates by organization and template name
- GETGet template version by organization, template, and name
- GETGet previous template version by organization, template, and name
- POSTCreate template version by organization
- GETGet all templates
- GETGet template examples
- GETGet template metadata by ID
- DELDelete template by ID
- PATCHUpdate template metadata by ID
- GETGet template DAUs by ID
- GETList template versions by template ID
- PATCHUpdate active template version by template ID
- POSTArchive template unused versions by template id
- GETGet template version by template ID and name
- GETGet template version by ID
- PATCHPatch template version by ID
- POSTArchive template version
- PATCHCancel template version by ID
- POSTCreate template version dry-run
- GETGet template version dry-run by job ID
- PATCHCancel template version dry-run by job ID
- GETGet template version dry-run logs by job ID
- GETGet template version dry-run resources by job ID
- GETGet external auth by template version
- GETGet logs by template version
- GETRemoved: Get parameters by template version
- GETGet resources by template version
- GETGet rich parameters by template version
- GETRemoved: Get schema by template version
- POSTUnarchive template version
- GETGet template variables by template version
WorkspaceProxies
Users
- GETGet users
- POSTCreate new user
- GETGet authentication methods
- GETCheck initial user created
- POSTCreate initial user
- POSTLog out user
- GETOAuth 2.0 GitHub Callback
- GETOpenID Connect Callback
- GETGet user by name
- DELDelete user
- PUTUpdate user appearance settings
- GETGet autofill build parameters for user
- GETGet user Git SSH key
- PUTRegenerate user SSH key
- POSTCreate new session key
- GETGet user tokens
- POSTCreate token API key
- GETGet API key by token name
- GETGet API key by ID
- DELDelete API key
- GETGet user login type
- GETGet organizations by user
- GETGet organization by user and organization name
- PUTUpdate user password
- PUTUpdate user profile
- GETGet user roles
- PUTAssign role to user
- PUTActivate user account
- PUTSuspend user account
Builds
- GETGet workspace build by user, workspace name, and build number
- GETGet workspace build
- PATCHCancel workspace build
- GETGet workspace build logs
- GETGet build parameters for workspace build
- GETRemoved: Get workspace resources for workspace build
- GETGet provisioner state for workspace build
- GETGet workspace build timings by ID
- GETGet workspace builds by workspace ID
- POSTCreate workspace build
Get connection info for workspace agent
curl --request GET \
--url https://cloud.local.wirtual.dev/api/v2/workspaceagents/{workspaceagent}/connection \
--header 'Wirtual-Session-Token: <api-key>'{
"derp_force_websockets": true,
"derp_map": {
"homeParams": {
"regionScore": {}
},
"omitDefaultRegions": true,
"regions": {}
},
"disable_direct_connections": true
}Authorizations
Path Parameters
Workspace agent ID
Response
HomeParams, if non-nil, is a change in home parameters.
The rest of the DEPRMap fields, if zero, means unchanged.
RegionScore scales latencies of DERP regions by a given scaling factor when determining which region to use as the home ("preferred") DERP. Scores in the range (0, 1) will cause this region to be proportionally more preferred, and scores in the range (1, ∞) will penalize a region.
If a region is not present in this map, it is treated as having a score of 1.0.
Scores should not be 0 or negative; such scores will be ignored.
A nil map means no change from the previous value (if any); an empty non-nil map can be sent to reset all scores back to 1.0.
OmitDefaultRegions specifies to not use Tailscale's DERP servers, and only use those specified in this DERPMap. If there are none set outside of the defaults, this is a noop.
This field is only meaningful if the Regions map is non-nil (indicating a change).
Regions is the set of geographic regions running DERP node(s).
It's keyed by the DERPRegion.RegionID.
The numbers are not necessarily contiguous.
Avoid is whether the client should avoid picking this as its home region. The region should only be used if a peer is there. Clients already using this region as their home should migrate away to a new region without Avoid set.
EmbeddedRelay is true when the region is bundled with the Coder control plane.
Nodes are the DERP nodes running in this region, in priority order for the current client. Client TLS connections should ideally only go to the first entry (falling back to the second if necessary). STUN packets should go to the first 1 or 2.
If nodes within a region route packets amongst themselves, but not to other regions. That said, each user/domain should get a the same preferred node order, so if all nodes for a user/network pick the first one (as they should, when things are healthy), the inter-cluster routing is minimal to zero.
CanPort80 specifies whether this DERP node is accessible over HTTP on port 80 specifically. This is used for captive portal checks.
CertName optionally specifies the expected TLS cert common name. If empty, HostName is used. If CertName is non-empty, HostName is only used for the TCP dial (if IPv4/IPv6 are not present) + TLS ClientHello.
DERPPort optionally provides an alternate TLS port number for the DERP HTTPS server.
If zero, 443 is used.
ForceHTTP is used by unit tests to force HTTP. It should not be set by users.
HostName is the DERP node's hostname.
It is required but need not be unique; multiple nodes may have the same HostName but vary in configuration otherwise.
InsecureForTests is used by unit tests to disable TLS verification. It should not be set by users.
IPv4 optionally forces an IPv4 address to use, instead of using DNS. If empty, A record(s) from DNS lookups of HostName are used. If the string is not an IPv4 address, IPv4 is not used; the conventional string to disable IPv4 (and not use DNS) is "none".
IPv6 optionally forces an IPv6 address to use, instead of using DNS. If empty, AAAA record(s) from DNS lookups of HostName are used. If the string is not an IPv6 address, IPv6 is not used; the conventional string to disable IPv6 (and not use DNS) is "none".
Name is a unique node name (across all regions). It is not a host name. It's typically of the form "1b", "2a", "3b", etc. (region ID + suffix within that region)
RegionID is the RegionID of the DERPRegion that this node is running in.
STUNOnly marks a node as only a STUN server and not a DERP server.
Port optionally specifies a STUN port to use. Zero means 3478. To disable STUN on this node, use -1.
STUNTestIP is used in tests to override the STUN server's IP. If empty, it's assumed to be the same as the DERP server.
RegionCode is a short name for the region. It's usually a popular city or airport code in the region: "nyc", "sf", "sin", "fra", etc.
RegionID is a unique integer for a geographic region.
It corresponds to the legacy derpN.tailscale.com hostnames used by older clients. (Older clients will continue to resolve derpN.tailscale.com when contacting peers, rather than use the server-provided DERPMap)
RegionIDs must be non-zero, positive, and guaranteed to fit in a JavaScript number.
RegionIDs in range 900-999 are reserved for end users to run their own DERP nodes.
RegionName is a long English name for the region: "New York City", "San Francisco", "Singapore", "Frankfurt", etc.
curl --request GET \
--url https://cloud.local.wirtual.dev/api/v2/workspaceagents/{workspaceagent}/connection \
--header 'Wirtual-Session-Token: <api-key>'{
"derp_force_websockets": true,
"derp_map": {
"homeParams": {
"regionScore": {}
},
"omitDefaultRegions": true,
"regions": {}
},
"disable_direct_connections": true
}