POST /v5/tunnels — freestyle

Create a tunnel, optionally attaching networks in the same call (vpcs, all-or-nothing). It lives until you delete it, and its config never changes: save it, bring it up once, and manage which networks it reaches by attaching and detaching them — no config updates, ever. Omit clientPublicKey and a keypair is minted for you — the response carries the only copy of the private key you will get.

Request body

clientPublicKeystring nullable

The public key of a keypair you already hold. Omit to have one minted for you; supply it and the platform never sees a private key at all.

displayNamestring nullable

A free-form label, for telling several tunnels apart.

routesstring[] nullable

The ranges your client will route through the tunnel — its AllowedIPs, fixed for the tunnel's life so attaching and detaching networks never changes your config. Omit for the default (10.0.0.0/8 and fd00::/8), which covers every network with default addressing. Only networks whose CIDRs fall inside the routes can be attached.

slugstring nullable

A URL-safe handle, unique within your account: 1–63 chars of [a-z0-9-], no leading, trailing, or repeated hyphens. Address the tunnel by it instead of by id.

Response

Tunnel ready, with any requested networks attached

clientAddressV4string required

Your fixed addresses inside the tunnel. Only the gateway ever sees them: each attached network sees an address inside its own subnet instead (attachments[].address).

clientAddressV6string required

clientConfigstring required

A complete WireGuard config file, fixed for the life of the tunnel: attaching and detaching networks never changes it, so bring it up once and manage what it reaches through the API. PrivateKey is blank except on create and rotate-key, the only two responses that mint a keypair.

clientPublicKeystring required

createdAtstring date-time required

displayNamestring nullable

Your label for this tunnel, if you gave it one.

endpointHoststring nullable

Host to dial.

endpointPortinteger required

idstring required

Deprecated: the tunnel's id under its old name. Read tunnelId.

routesstring[] required

The ranges your client routes through the tunnel — its AllowedIPs, fixed at create. A network can only be attached if its CIDRs fall inside these.

serverPublicKeystring required

The one [Peer] public key in your config.

slugstring nullable

Your handle for this tunnel, if you gave it one. Usable anywhere the id is, in place of it.

tunnelIdstring nullable

The tunnel's id, under the name the rest of the API uses for it — a firewall rule says tunnelId, so the tunnel does too.

updatedAtstring date-time required

clientPrivateKeystring required

Returned once. Already embedded in clientConfig.

Request body

Response

Changes