Skip to content
Open Console →

Mesh networks

12 endpoints under /api/v1/mesh.

GET /api/v1/mesh/networks #

List the active organization's Networks

Responses

200 Live Network list (read-through from the shard).
Response body
  • networksNetwork[]required
    Show fields
    • namestringrequired
    • cidrstringrequired
    • relayobjectrequired
      Show fields
      • enabledbooleanrequired
    • phasestringrequired
    • loginServerstring
    • oidcJoinRulesOIDCJoinRule[]required
      Show fields
      • namestringrequired
      • issuerstring · urirequired
      • audiencestringrequired
      • subjectPatternsstring[]required
      • tagsstring[]required
      • keyTTLSecondsinteger
401 Unauthenticated.
Response body
  • errorstringrequired
403 Forbidden (not in the Mesh beta, or org mismatch).
Response body
  • errorstringrequired
404 Unknown network.
Response body
  • errorstringrequired
502 The shard or the Network's coordination plane is unreachable.
Response body
  • errorstringrequired
POST /api/v1/mesh/networks #

Create a Network

Request body

  • namestringrequired
  • cidrstring
  • relayobject
    Show fields
    • enabledbooleanrequired

Responses

201 Network accepted for provisioning.
Response body
  • namestringrequired
  • cidrstringrequired
  • relayobjectrequired
    Show fields
    • enabledbooleanrequired
  • phasestringrequired
  • loginServerstring
  • oidcJoinRulesOIDCJoinRule[]required
    Show fields
    • namestringrequired
    • issuerstring · urirequired
    • audiencestringrequired
    • subjectPatternsstring[]required
    • tagsstring[]required
    • keyTTLSecondsinteger
401 Unauthenticated.
Response body
  • errorstringrequired
403 Forbidden (not in the Mesh beta, or org mismatch).
Response body
  • errorstringrequired
404 Unknown network.
Response body
  • errorstringrequired
502 The shard or the Network's coordination plane is unreachable.
Response body
  • errorstringrequired
GET /api/v1/mesh/networks/{network} #

Network status (read-through)

Parameters

  • network path string required

Responses

200 The Network, straight from the shard.
Response body
  • namestringrequired
  • cidrstringrequired
  • relayobjectrequired
    Show fields
    • enabledbooleanrequired
  • phasestringrequired
  • loginServerstring
  • oidcJoinRulesOIDCJoinRule[]required
    Show fields
    • namestringrequired
    • issuerstring · urirequired
    • audiencestringrequired
    • subjectPatternsstring[]required
    • tagsstring[]required
    • keyTTLSecondsinteger
401 Unauthenticated.
Response body
  • errorstringrequired
403 Forbidden (not in the Mesh beta, or org mismatch).
Response body
  • errorstringrequired
404 Unknown network.
Response body
  • errorstringrequired
502 The shard or the Network's coordination plane is unreachable.
Response body
  • errorstringrequired
PATCH /api/v1/mesh/networks/{network} #

Update a Network (relay toggle, OIDC join rules)

Parameters

  • network path string required

Request body

  • relayobject
    Show fields
    • enabledbooleanrequired
  • oidcJoinRulesOIDCJoinRule[]
    Show fields
    • namestringrequired
    • issuerstring · urirequired
    • audiencestringrequired
    • subjectPatternsstring[]required
    • tagsstring[]required
    • keyTTLSecondsinteger

Responses

200 The updated Network.
Response body
  • namestringrequired
  • cidrstringrequired
  • relayobjectrequired
    Show fields
    • enabledbooleanrequired
  • phasestringrequired
  • loginServerstring
  • oidcJoinRulesOIDCJoinRule[]required
    Show fields
    • namestringrequired
    • issuerstring · urirequired
    • audiencestringrequired
    • subjectPatternsstring[]required
    • tagsstring[]required
    • keyTTLSecondsinteger
401 Unauthenticated.
Response body
  • errorstringrequired
403 Forbidden (not in the Mesh beta, or org mismatch).
Response body
  • errorstringrequired
404 Unknown network.
Response body
  • errorstringrequired
502 The shard or the Network's coordination plane is unreachable.
Response body
  • errorstringrequired
DELETE /api/v1/mesh/networks/{network} #

Delete a Network

Tears down the coordination plane, relay, and every machine registration. Asynchronous on the shard; the record is soft-deleted for billing lineage.

Parameters

  • network path string required

Responses

202 Deletion accepted.
401 Unauthenticated.
Response body
  • errorstringrequired
403 Forbidden (not in the Mesh beta, or org mismatch).
Response body
  • errorstringrequired
404 Unknown network.
Response body
  • errorstringrequired
502 The shard or the Network's coordination plane is unreachable.
Response body
  • errorstringrequired
GET /api/v1/mesh/networks/{network}/policy #

The Network's Policy (verbatim HuJSON)

Parameters

  • network path string required

Responses

200 The Policy document; empty policy + default=allow-all is the create-time posture.
Response body
  • policystringrequired
  • updatedAtstring
  • defaultstring
401 Unauthenticated.
Response body
  • errorstringrequired
403 Forbidden (not in the Mesh beta, or org mismatch).
Response body
  • errorstringrequired
404 Unknown network.
Response body
  • errorstringrequired
502 The shard or the Network's coordination plane is unreachable.
Response body
  • errorstringrequired
PUT /api/v1/mesh/networks/{network}/policy #

Replace the Network's Policy

The verbatim HuJSON document (ADR 0038 §4). The coordination plane validates syntax/schema; a rejection returns 400 with its reason.

Parameters

  • network path string required

Request body

  • policystringrequired

Responses

200 The stored Policy.
Response body
  • policystringrequired
  • updatedAtstring
  • defaultstring
400 The coordination plane rejected the document.
Response body
  • errorstringrequired
401 Unauthenticated.
Response body
  • errorstringrequired
403 Forbidden (not in the Mesh beta, or org mismatch).
Response body
  • errorstringrequired
404 Unknown network.
Response body
  • errorstringrequired
502 The shard or the Network's coordination plane is unreachable.
Response body
  • errorstringrequired
GET /api/v1/mesh/networks/{network}/machines #

List the Network's Machines

Parameters

  • network path string required

Responses

200 Live machine list (read-through from the coordination plane).
Response body
  • machinesMachine[]required
    Show fields
    • idstringrequired
    • namestringrequired
    • addressesstring[]required
    • tagsstring[]required
    • onlinebooleanrequired
    • lastSeenstring
401 Unauthenticated.
Response body
  • errorstringrequired
403 Forbidden (not in the Mesh beta, or org mismatch).
Response body
  • errorstringrequired
404 Unknown network.
Response body
  • errorstringrequired
502 The shard or the Network's coordination plane is unreachable.
Response body
  • errorstringrequired
GET /api/v1/mesh/networks/{network}/join-keys #

List Join keys

Parameters

  • network path string required

Responses

200 The Network's Join keys (key material included — a Join key is a distributable machine-admission credential).
Response body
  • joinKeysJoinKey[]required
    Show fields
    • idstringrequired
    • keystringrequired
    • tagsstring[]required
    • reusablebooleanrequired
    • ephemeralbooleanrequired
    • usedbooleanrequired
    • expirationstring
    • createdAtstring
401 Unauthenticated.
Response body
  • errorstringrequired
403 Forbidden (not in the Mesh beta, or org mismatch).
Response body
  • errorstringrequired
404 Unknown network.
Response body
  • errorstringrequired
502 The shard or the Network's coordination plane is unreachable.
Response body
  • errorstringrequired
POST /api/v1/mesh/networks/{network}/join-keys #

Mint a Join key

Parameters

  • network path string required

Request body

  • tagsstring[]required
  • reusableboolean
  • ephemeralboolean
  • expiresInSecondsinteger

Responses

201 The Join key + the one-command join (`tailscale up …`).
Response body
  • joinKeyobjectrequired
    Show fields
    • idstringrequired
    • keystringrequired
    • tagsstring[]required
    • reusablebooleanrequired
    • ephemeralbooleanrequired
    • usedbooleanrequired
    • expirationstring
    • createdAtstring
  • joinCommandstringrequired
401 Unauthenticated.
Response body
  • errorstringrequired
403 Forbidden (not in the Mesh beta, or org mismatch).
Response body
  • errorstringrequired
404 Unknown network.
Response body
  • errorstringrequired
502 The shard or the Network's coordination plane is unreachable.
Response body
  • errorstringrequired
DELETE /api/v1/mesh/networks/{network}/machines/{id} #

Remove a Machine

Parameters

  • network path string required
  • id path string required

Responses

204 Machine removed; its agent is cut off at the next map poll.
401 Unauthenticated.
Response body
  • errorstringrequired
403 Forbidden (not in the Mesh beta, or org mismatch).
Response body
  • errorstringrequired
404 Unknown network.
Response body
  • errorstringrequired
502 The shard or the Network's coordination plane is unreachable.
Response body
  • errorstringrequired
POST /api/v1/mesh/networks/{network}/join-keys/expire #

Revoke a Join key

Expires the key so it admits no further machines. Already-joined machines are unaffected — revocation gates admission, not membership.

Parameters

  • network path string required

Request body

  • keystringrequired

Responses

204 Key expired.
401 Unauthenticated.
Response body
  • errorstringrequired
403 Forbidden (not in the Mesh beta, or org mismatch).
Response body
  • errorstringrequired
404 Unknown network.
Response body
  • errorstringrequired
502 The shard or the Network's coordination plane is unreachable.
Response body
  • errorstringrequired