AnkraDocs
Console

API reference · Networking

VPN gateways

13 operations of the Ankra Cloud API: VPN gateways - WireGuard or Headscale (Tailscale clients) into one or more private networks.

List VPN gateways#

GET/v1/vpn-gateways
Operation
list_vpn_gateways
Credentials
API token, Portal session
Requires
Permission read

Without the per-network addresses, the public key and health; get one for those.

Parameters

Parameters
NameInTypeDescription
cursorquerystringThe next_cursor of the previous page.
limitqueryintegerPage size; the server applies its default and maximum.

Responses

200A page of VPN gateways, newest first.application/json

200 response fields
FieldTypeDescription
itemsrequiredarray of VpnGateway
idrequiredstring
zonerequiredstring
namerequiredstring
planrequiredstring
staterequiredstringOne of creating, running, error, deleting
moderequiredstringOne of wireguard, headscale
hostnamerequiredstring | nullA headscale gateway's DNS name; point it at public_ipv4 and public_ipv6.
login_serverrequiredstring | nullWhat Tailscale clients log in to (https://<hostname>); null for wireguard.
network_idsrequiredarray of string
networksrequiredarray of VpnGatewayNetworkEmpty in lists.
idrequiredstring
namerequiredstring
cidrrequiredstringThe network's IPv4 subnet, routed to the peers.
addressrequiredstring | nullThe gateway's own address on the network, where VPN traffic comes from. Null in lists and until placed.
tunnel_networkrequiredstring
tunnel_addressrequiredstringThe gateway's own address in the tunnel network.
listen_portrequiredinteger
public_ipv4requiredstring | null
public_ipv6requiredstring | null
endpointrequiredstring | nullWhat peers dial: <ipv4>:51820, or [<ipv6>]:51820 without the IPv4 add-on. Null in lists and until placed.
public_keyrequiredstring | nullThe gateway's WireGuard public key, generated on its VM. Null in lists and until the gateway reported it.
peer_countrequiredinteger
is_healthyrequiredbooleanFalse in lists.
health_detailrequiredstringEmpty in lists.
configuration_generationrequiredinteger
dnsrequiredVpnGatewayDns | nullA headscale gateway's last step, on GET /v1/vpn-gateways/{id} once the gateway holds its addresses: the records to create for its hostname at your DNS provider and whether the name resolves to them now (checked at most every 30 s). Devices join once it does. Null for a wireguard gateway, in lists and before the gateway has addresses.
hostnamerequiredstring
recordsrequiredarray of object
typerequiredstringOne of A, AAAA
namerequiredstring
valuerequiredstring
is_readyrequiredbooleanThe hostname resolves to every record's address.
instructionsrequiredstringWhat to do, in one sentence for a person.
problemrequiredstring | nullWhy the name is not ready; null when it is.
active_operationrequiredOperation | null
idrequiredstring
kindrequiredstringOne of server.create, server.metadata, server.start, server.stop, server.restart, server.delete, server.force_release, server.network_quarantine, server.network_release, server.change_plan, server.rebuild, server.renumber_ipv6, server.renumber_ipv4, server.provider_router_resize, server.add_public_ipv4, server.remove_public_ipv4, server.settle_public_ipv4, server.attach_network, server.detach_network, server.firewall, storage.create, storage.attach, storage.detach, storage.resize, storage.delete, storage.backup, backup.restore, backup.delete, template.create, template.copy, template.delete, snapshot.create, snapshot.delete, router.sync, floating_ip.sync, network.sync, public_pool.sync, zone.topology_sync, server.move, server.migrate, server.recover, server.settle_migration, node.cordon, node.uncordon, node.drain, node.fence, node.maintenance, node.agent_upgrade, node.retire, node.withdraw_retirement, node.provision, load_balancer.create, load_balancer.delete, database.create, database.delete, database.restore, database.change_plan, database.start, database.resize, edge.sync, edge.delete, vpn_gateway.sync, vpn_gateway.delete, storage.move, storage.rebalance_policy, storage.drain_host, object_storage.migrate, object_storage.migrate_zone, object_storage.cut_over_zone, kubernetes_cluster.create, kubernetes_cluster.delete, kubernetes_cluster.upgrade, kubernetes_cluster.snapshot, kubernetes_cluster.restore, node_pool.sync, node_pool.delete, kubernetes_host.bootstrap, kubernetes_host.scale, kubernetes_cluster.platform_register, kubernetes_cluster.platform_deregister, control_plane.expand, control_plane.shrink, backup.verify
server_idrequiredstring | null
storage_idrequiredstring | null
backup_idrequiredstring | null
template_idrequiredstring | null
router_idrequiredstring | null
floating_ip_idrequiredstring | null
node_idstringSet on node maintenance operations (operator only); absent otherwise.
load_balancer_idstring | nullSet on the operations that create and delete a load balancer.
database_idstring | nullSet on the operations that create and delete a managed database.
edge_idstring | nullSet on the operations that sync and delete a network edge.
vpn_gateway_idstring | nullSet on the operations that sync and delete a VPN gateway.
snapshot_idstring | nullSet on the operations that create and delete a snapshot, and on a storage.create that clones one.
kubernetes_cluster_idstring | nullSet on the operations of a managed Kubernetes cluster.
node_pool_idstring | nullSet on the operations of a Kubernetes node pool.
kubernetes_host_idstringSet on a regional host cluster bootstrap (operator only); absent otherwise.
statusrequiredstringOne of pending, running, succeeded, failed, cancelled
steprequiredstringMachine name of the current step, e.g. create_disk or transfer_cross_zone.
step_indexrequiredinteger
step_countrequiredinteger
errorrequiredstringEmpty unless the operation failed.
created_atrequiredstring (date-time)
started_atrequiredstring (date-time) | null
finished_atrequiredstring (date-time) | null
deadline_atrequiredstring (date-time)
actorstringWho asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations.
progressMigrationProgressPresent on GET /v1/operations/{id} while a server.migrate drives a live transfer.
staterequiredstringOne of reserved, detached, preparing, sending, switched, aborting
source_node_idrequiredstring
target_node_idrequiredstring
phaserequiredstringHow far the nodes report the current attempt.One of , preparing, transferring, completed, failed
attemptrequiredintegerWhich send this is under the convergence policy, from 1.
iterationrequiredintegerMemory passes so far in the current attempt.
transferred_bytesrequiredinteger
total_bytesrequiredinteger0 when the hypervisor does not report it.
dirty_bytes_per_secondrequiredinteger
downtime_millisecondsrequiredintegerThe pause the guest took at handover, once completed.
detailrequiredstring
reported_atrequiredstring (date-time) | nullThe reporting node's clock.
eventsarray of OperationEventPresent on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first.
atrequiredstring (date-time)
kindrequiredstringFor example target_chosen, send_started, handed_over, undoing, cold_fallback, move_cancelled, recovery_started, succeeded, failed.
messagerequiredstring
datarequiredobject
created_atrequiredstring (date-time)
next_cursorrequiredstring | nullPass as ?cursor= for the next page; null on the last page.
  • 400The request is invalid; detail says why.
  • 401Not signed in, or the credential is invalid or expired.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • defaultAny other error, usually 500.

Example

bash
curl 'https://cloud.ankra.app/v1/vpn-gateways' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

Create a WireGuard or Headscale VPN gateway that reaches one or more private networks#

POST/v1/vpn-gateways
Operation
create_vpn_gateway
Credentials
API token, Portal session
Requires
Permission operate

One managed VM (vpn-<id>) in the networks' zone with a leg on every network in network_ids (1 to 7, all in one zone), a public IPv6 /64 and, with public_ipv4 (the default), the public IPv4 add-on. Traffic from the VPN is masqueraded onto the gateway's own address on each network, so the networks' servers need no route or change of their own. Nothing is forwarded to the internet or between the networks. Billed at its plan plus the IPv4 add-on.

mode picks how devices get in:

  • wireguard (the default): WireGuard on UDP 51820. Peers added under /v1/vpn-gateways/{id}/peers are named by their public keys and reach every network. The gateway generates its own key on the VM; only public_key leaves it.
  • headscale: a Headscale control server for hostname, a DNS name you point at the gateway's addresses (A to public_ipv4, AAAA to public_ipv6); it obtains its own Let's Encrypt certificate once the name resolves. Devices join with the Tailscale apps and a key from /v1/vpn-gateways/{id}/auth-keys, and the gateway is the tailnet's subnet router for its networks. Devices also reach each other. No Headscale credential leaves the VM.

Parameters

Parameters
NameInTypeDescription
Idempotency-KeyheaderstringA key the client chooses for this create, for example a UUID. The same create sent again with the same key within 24 hours answers the first one's answer with Idempotent-Replayed: true and creates nothing. 409 with reason: idempotency_key_in_progress while the first request is still running (try again shortly), with reason: idempotency_key_outcome_unknown when the first request answered 5xx or never finished (the create may or may not exist: list the resource before creating again with a new key), or with reason: idempotency_key_answer_not_stored when the create succeeded but its answer could not be kept (read the resource). 422 with reason: idempotency_key_reused when the key was used with a different request, 400 when the key is not 1 to 255 visible ASCII characters. Only a 4xx answer frees a key before the 24 hours.

Request bodyapplication/json · CreateVpnGatewayRequest

Request body fields
FieldTypeDescription
network_idsrequiredarray of stringThe private networks the gateway reaches, all in one zone; the gateway runs in that zone.
namestringDefaults to "<first network name> VPN".
planstring
tunnel_networkstringThe IPv4 network (/16 to /28, private or 100.64.0.0/10) peers get their addresses from; it must not overlap a network of the gateway.
public_ipv4booleanGive the gateway the public IPv4 add-on, so peers on IPv4-only networks reach it; without it peers connect over IPv6.
modestringOne of wireguard, headscale
hostnamestringHeadscale only, and required there: the DNS name the gateway serves, which you point at it. tunnel_network is for wireguard only.

Responses

202The VPN gateway and its vpn_gateway.sync operation.application/json

202 response fields
FieldTypeDescription
vpn_gatewayrequiredVpnGateway
idrequiredstring
zonerequiredstring
namerequiredstring
planrequiredstring
staterequiredstringOne of creating, running, error, deleting
moderequiredstringOne of wireguard, headscale
hostnamerequiredstring | nullA headscale gateway's DNS name; point it at public_ipv4 and public_ipv6.
login_serverrequiredstring | nullWhat Tailscale clients log in to (https://<hostname>); null for wireguard.
network_idsrequiredarray of string
networksrequiredarray of VpnGatewayNetworkEmpty in lists.
idrequiredstring
namerequiredstring
cidrrequiredstringThe network's IPv4 subnet, routed to the peers.
addressrequiredstring | nullThe gateway's own address on the network, where VPN traffic comes from. Null in lists and until placed.
tunnel_networkrequiredstring
tunnel_addressrequiredstringThe gateway's own address in the tunnel network.
listen_portrequiredinteger
public_ipv4requiredstring | null
public_ipv6requiredstring | null
endpointrequiredstring | nullWhat peers dial: <ipv4>:51820, or [<ipv6>]:51820 without the IPv4 add-on. Null in lists and until placed.
public_keyrequiredstring | nullThe gateway's WireGuard public key, generated on its VM. Null in lists and until the gateway reported it.
peer_countrequiredinteger
is_healthyrequiredbooleanFalse in lists.
health_detailrequiredstringEmpty in lists.
configuration_generationrequiredinteger
dnsrequiredVpnGatewayDns | nullA headscale gateway's last step, on GET /v1/vpn-gateways/{id} once the gateway holds its addresses: the records to create for its hostname at your DNS provider and whether the name resolves to them now (checked at most every 30 s). Devices join once it does. Null for a wireguard gateway, in lists and before the gateway has addresses.
hostnamerequiredstring
recordsrequiredarray of object
typerequiredstringOne of A, AAAA
namerequiredstring
valuerequiredstring
is_readyrequiredbooleanThe hostname resolves to every record's address.
instructionsrequiredstringWhat to do, in one sentence for a person.
problemrequiredstring | nullWhy the name is not ready; null when it is.
active_operationrequiredOperation | null
idrequiredstring
kindrequiredstringOne of server.create, server.metadata, server.start, server.stop, server.restart, server.delete, server.force_release, server.network_quarantine, server.network_release, server.change_plan, server.rebuild, server.renumber_ipv6, server.renumber_ipv4, server.provider_router_resize, server.add_public_ipv4, server.remove_public_ipv4, server.settle_public_ipv4, server.attach_network, server.detach_network, server.firewall, storage.create, storage.attach, storage.detach, storage.resize, storage.delete, storage.backup, backup.restore, backup.delete, template.create, template.copy, template.delete, snapshot.create, snapshot.delete, router.sync, floating_ip.sync, network.sync, public_pool.sync, zone.topology_sync, server.move, server.migrate, server.recover, server.settle_migration, node.cordon, node.uncordon, node.drain, node.fence, node.maintenance, node.agent_upgrade, node.retire, node.withdraw_retirement, node.provision, load_balancer.create, load_balancer.delete, database.create, database.delete, database.restore, database.change_plan, database.start, database.resize, edge.sync, edge.delete, vpn_gateway.sync, vpn_gateway.delete, storage.move, storage.rebalance_policy, storage.drain_host, object_storage.migrate, object_storage.migrate_zone, object_storage.cut_over_zone, kubernetes_cluster.create, kubernetes_cluster.delete, kubernetes_cluster.upgrade, kubernetes_cluster.snapshot, kubernetes_cluster.restore, node_pool.sync, node_pool.delete, kubernetes_host.bootstrap, kubernetes_host.scale, kubernetes_cluster.platform_register, kubernetes_cluster.platform_deregister, control_plane.expand, control_plane.shrink, backup.verify
server_idrequiredstring | null
storage_idrequiredstring | null
backup_idrequiredstring | null
template_idrequiredstring | null
router_idrequiredstring | null
floating_ip_idrequiredstring | null
node_idstringSet on node maintenance operations (operator only); absent otherwise.
load_balancer_idstring | nullSet on the operations that create and delete a load balancer.
database_idstring | nullSet on the operations that create and delete a managed database.
edge_idstring | nullSet on the operations that sync and delete a network edge.
vpn_gateway_idstring | nullSet on the operations that sync and delete a VPN gateway.
snapshot_idstring | nullSet on the operations that create and delete a snapshot, and on a storage.create that clones one.
kubernetes_cluster_idstring | nullSet on the operations of a managed Kubernetes cluster.
node_pool_idstring | nullSet on the operations of a Kubernetes node pool.
kubernetes_host_idstringSet on a regional host cluster bootstrap (operator only); absent otherwise.
statusrequiredstringOne of pending, running, succeeded, failed, cancelled
steprequiredstringMachine name of the current step, e.g. create_disk or transfer_cross_zone.
step_indexrequiredinteger
step_countrequiredinteger
errorrequiredstringEmpty unless the operation failed.
created_atrequiredstring (date-time)
started_atrequiredstring (date-time) | null
finished_atrequiredstring (date-time) | null
deadline_atrequiredstring (date-time)
actorstringWho asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations.
progressMigrationProgressPresent on GET /v1/operations/{id} while a server.migrate drives a live transfer.
staterequiredstringOne of reserved, detached, preparing, sending, switched, aborting
source_node_idrequiredstring
target_node_idrequiredstring
phaserequiredstringHow far the nodes report the current attempt.One of , preparing, transferring, completed, failed
attemptrequiredintegerWhich send this is under the convergence policy, from 1.
iterationrequiredintegerMemory passes so far in the current attempt.
transferred_bytesrequiredinteger
total_bytesrequiredinteger0 when the hypervisor does not report it.
dirty_bytes_per_secondrequiredinteger
downtime_millisecondsrequiredintegerThe pause the guest took at handover, once completed.
detailrequiredstring
reported_atrequiredstring (date-time) | nullThe reporting node's clock.
eventsarray of OperationEventPresent on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first.
atrequiredstring (date-time)
kindrequiredstringFor example target_chosen, send_started, handed_over, undoing, cold_fallback, move_cancelled, recovery_started, succeeded, failed.
messagerequiredstring
datarequiredobject
created_atrequiredstring (date-time)
operationrequiredOperation
idrequiredstring
kindrequiredstringOne of server.create, server.metadata, server.start, server.stop, server.restart, server.delete, server.force_release, server.network_quarantine, server.network_release, server.change_plan, server.rebuild, server.renumber_ipv6, server.renumber_ipv4, server.provider_router_resize, server.add_public_ipv4, server.remove_public_ipv4, server.settle_public_ipv4, server.attach_network, server.detach_network, server.firewall, storage.create, storage.attach, storage.detach, storage.resize, storage.delete, storage.backup, backup.restore, backup.delete, template.create, template.copy, template.delete, snapshot.create, snapshot.delete, router.sync, floating_ip.sync, network.sync, public_pool.sync, zone.topology_sync, server.move, server.migrate, server.recover, server.settle_migration, node.cordon, node.uncordon, node.drain, node.fence, node.maintenance, node.agent_upgrade, node.retire, node.withdraw_retirement, node.provision, load_balancer.create, load_balancer.delete, database.create, database.delete, database.restore, database.change_plan, database.start, database.resize, edge.sync, edge.delete, vpn_gateway.sync, vpn_gateway.delete, storage.move, storage.rebalance_policy, storage.drain_host, object_storage.migrate, object_storage.migrate_zone, object_storage.cut_over_zone, kubernetes_cluster.create, kubernetes_cluster.delete, kubernetes_cluster.upgrade, kubernetes_cluster.snapshot, kubernetes_cluster.restore, node_pool.sync, node_pool.delete, kubernetes_host.bootstrap, kubernetes_host.scale, kubernetes_cluster.platform_register, kubernetes_cluster.platform_deregister, control_plane.expand, control_plane.shrink, backup.verify
server_idrequiredstring | null
storage_idrequiredstring | null
backup_idrequiredstring | null
template_idrequiredstring | null
router_idrequiredstring | null
floating_ip_idrequiredstring | null
node_idstringSet on node maintenance operations (operator only); absent otherwise.
load_balancer_idstring | nullSet on the operations that create and delete a load balancer.
database_idstring | nullSet on the operations that create and delete a managed database.
edge_idstring | nullSet on the operations that sync and delete a network edge.
vpn_gateway_idstring | nullSet on the operations that sync and delete a VPN gateway.
snapshot_idstring | nullSet on the operations that create and delete a snapshot, and on a storage.create that clones one.
kubernetes_cluster_idstring | nullSet on the operations of a managed Kubernetes cluster.
node_pool_idstring | nullSet on the operations of a Kubernetes node pool.
kubernetes_host_idstringSet on a regional host cluster bootstrap (operator only); absent otherwise.
statusrequiredstringOne of pending, running, succeeded, failed, cancelled
steprequiredstringMachine name of the current step, e.g. create_disk or transfer_cross_zone.
step_indexrequiredinteger
step_countrequiredinteger
errorrequiredstringEmpty unless the operation failed.
created_atrequiredstring (date-time)
started_atrequiredstring (date-time) | null
finished_atrequiredstring (date-time) | null
deadline_atrequiredstring (date-time)
actorstringWho asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations.
progressMigrationProgressPresent on GET /v1/operations/{id} while a server.migrate drives a live transfer.
staterequiredstringOne of reserved, detached, preparing, sending, switched, aborting
source_node_idrequiredstring
target_node_idrequiredstring
phaserequiredstringHow far the nodes report the current attempt.One of , preparing, transferring, completed, failed
attemptrequiredintegerWhich send this is under the convergence policy, from 1.
iterationrequiredintegerMemory passes so far in the current attempt.
transferred_bytesrequiredinteger
total_bytesrequiredinteger0 when the hypervisor does not report it.
dirty_bytes_per_secondrequiredinteger
downtime_millisecondsrequiredintegerThe pause the guest took at handover, once completed.
detailrequiredstring
reported_atrequiredstring (date-time) | nullThe reporting node's clock.
eventsarray of OperationEventPresent on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first.
atrequiredstring (date-time)
kindrequiredstringFor example target_chosen, send_started, handed_over, undoing, cold_fallback, move_cancelled, recovery_started, succeeded, failed.
messagerequiredstring
datarequiredobject
  • 400The request is invalid; detail says why.
  • 401Not signed in, or the credential is invalid or expired.
  • 402The account may not create this. reason is payment_method_required while it has no default payment method and its credit does not cover the create: the credit left must cover one month, at monthly list prices, of everything the account already runs plus what the create adds (add a payment method through POST /v1/account/billing/setup-session, or free what the account no longer needs); owner_approval_required while its owner has not approved paid usage and no credit is left; or account_suspended while an invoice is overdue past the grace period (pay it) or Ankra staff suspended the account (contact support). A prepaid account (linked to an Ankra platform organisation) is refused with payment_method_required while it has no card, and with credit_required once it has one but its credit does not cover the create: Cloud never charges its card, so only a top-up on the Ankra platform lifts it, and top_up_url names that page when Cloud knows it. GET /v1/account/billing reports the same standing. For payment_method_required and credit_required, detail names what the create costs, the credit left and the committed monthly spend only to a principal that may read billing (billing.read, and for an API token a scope that includes it); anyone else is told only that the credit does not cover it.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 404No such resource in the caller's account.
  • 409The resource's state does not allow this now.
  • 422The account would exceed a quota; detail names the limit and reason is quota_exceeded.
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • 503No capacity or address is free in the zone right now (reason: capacity_unavailable, with availability wording in detail), or a host did not answer; try another plan or zone, or try again later.
  • defaultAny other error, usually 500.

Example

bash
curl -X POST 'https://cloud.ankra.app/v1/vpn-gateways' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "network_ids": [
    "string"
  ]
}'

Get a VPN gateway with its addresses on every network, its public key and health#

GET/v1/vpn-gateways/{id}
Operation
get_vpn_gateway
Credentials
API token, Portal session
Requires
Permission read

Parameters

Parameters
NameInTypeDescription
idrequiredpathstring

Responses

200The VPN gateway.application/json

200 response fields
FieldTypeDescription
vpn_gatewayrequiredVpnGateway
idrequiredstring
zonerequiredstring
namerequiredstring
planrequiredstring
staterequiredstringOne of creating, running, error, deleting
moderequiredstringOne of wireguard, headscale
hostnamerequiredstring | nullA headscale gateway's DNS name; point it at public_ipv4 and public_ipv6.
login_serverrequiredstring | nullWhat Tailscale clients log in to (https://<hostname>); null for wireguard.
network_idsrequiredarray of string
networksrequiredarray of VpnGatewayNetworkEmpty in lists.
idrequiredstring
namerequiredstring
cidrrequiredstringThe network's IPv4 subnet, routed to the peers.
addressrequiredstring | nullThe gateway's own address on the network, where VPN traffic comes from. Null in lists and until placed.
tunnel_networkrequiredstring
tunnel_addressrequiredstringThe gateway's own address in the tunnel network.
listen_portrequiredinteger
public_ipv4requiredstring | null
public_ipv6requiredstring | null
endpointrequiredstring | nullWhat peers dial: <ipv4>:51820, or [<ipv6>]:51820 without the IPv4 add-on. Null in lists and until placed.
public_keyrequiredstring | nullThe gateway's WireGuard public key, generated on its VM. Null in lists and until the gateway reported it.
peer_countrequiredinteger
is_healthyrequiredbooleanFalse in lists.
health_detailrequiredstringEmpty in lists.
configuration_generationrequiredinteger
dnsrequiredVpnGatewayDns | nullA headscale gateway's last step, on GET /v1/vpn-gateways/{id} once the gateway holds its addresses: the records to create for its hostname at your DNS provider and whether the name resolves to them now (checked at most every 30 s). Devices join once it does. Null for a wireguard gateway, in lists and before the gateway has addresses.
hostnamerequiredstring
recordsrequiredarray of object
typerequiredstringOne of A, AAAA
namerequiredstring
valuerequiredstring
is_readyrequiredbooleanThe hostname resolves to every record's address.
instructionsrequiredstringWhat to do, in one sentence for a person.
problemrequiredstring | nullWhy the name is not ready; null when it is.
active_operationrequiredOperation | null
idrequiredstring
kindrequiredstringOne of server.create, server.metadata, server.start, server.stop, server.restart, server.delete, server.force_release, server.network_quarantine, server.network_release, server.change_plan, server.rebuild, server.renumber_ipv6, server.renumber_ipv4, server.provider_router_resize, server.add_public_ipv4, server.remove_public_ipv4, server.settle_public_ipv4, server.attach_network, server.detach_network, server.firewall, storage.create, storage.attach, storage.detach, storage.resize, storage.delete, storage.backup, backup.restore, backup.delete, template.create, template.copy, template.delete, snapshot.create, snapshot.delete, router.sync, floating_ip.sync, network.sync, public_pool.sync, zone.topology_sync, server.move, server.migrate, server.recover, server.settle_migration, node.cordon, node.uncordon, node.drain, node.fence, node.maintenance, node.agent_upgrade, node.retire, node.withdraw_retirement, node.provision, load_balancer.create, load_balancer.delete, database.create, database.delete, database.restore, database.change_plan, database.start, database.resize, edge.sync, edge.delete, vpn_gateway.sync, vpn_gateway.delete, storage.move, storage.rebalance_policy, storage.drain_host, object_storage.migrate, object_storage.migrate_zone, object_storage.cut_over_zone, kubernetes_cluster.create, kubernetes_cluster.delete, kubernetes_cluster.upgrade, kubernetes_cluster.snapshot, kubernetes_cluster.restore, node_pool.sync, node_pool.delete, kubernetes_host.bootstrap, kubernetes_host.scale, kubernetes_cluster.platform_register, kubernetes_cluster.platform_deregister, control_plane.expand, control_plane.shrink, backup.verify
server_idrequiredstring | null
storage_idrequiredstring | null
backup_idrequiredstring | null
template_idrequiredstring | null
router_idrequiredstring | null
floating_ip_idrequiredstring | null
node_idstringSet on node maintenance operations (operator only); absent otherwise.
load_balancer_idstring | nullSet on the operations that create and delete a load balancer.
database_idstring | nullSet on the operations that create and delete a managed database.
edge_idstring | nullSet on the operations that sync and delete a network edge.
vpn_gateway_idstring | nullSet on the operations that sync and delete a VPN gateway.
snapshot_idstring | nullSet on the operations that create and delete a snapshot, and on a storage.create that clones one.
kubernetes_cluster_idstring | nullSet on the operations of a managed Kubernetes cluster.
node_pool_idstring | nullSet on the operations of a Kubernetes node pool.
kubernetes_host_idstringSet on a regional host cluster bootstrap (operator only); absent otherwise.
statusrequiredstringOne of pending, running, succeeded, failed, cancelled
steprequiredstringMachine name of the current step, e.g. create_disk or transfer_cross_zone.
step_indexrequiredinteger
step_countrequiredinteger
errorrequiredstringEmpty unless the operation failed.
created_atrequiredstring (date-time)
started_atrequiredstring (date-time) | null
finished_atrequiredstring (date-time) | null
deadline_atrequiredstring (date-time)
actorstringWho asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations.
progressMigrationProgressPresent on GET /v1/operations/{id} while a server.migrate drives a live transfer.
staterequiredstringOne of reserved, detached, preparing, sending, switched, aborting
source_node_idrequiredstring
target_node_idrequiredstring
phaserequiredstringHow far the nodes report the current attempt.One of , preparing, transferring, completed, failed
attemptrequiredintegerWhich send this is under the convergence policy, from 1.
iterationrequiredintegerMemory passes so far in the current attempt.
transferred_bytesrequiredinteger
total_bytesrequiredinteger0 when the hypervisor does not report it.
dirty_bytes_per_secondrequiredinteger
downtime_millisecondsrequiredintegerThe pause the guest took at handover, once completed.
detailrequiredstring
reported_atrequiredstring (date-time) | nullThe reporting node's clock.
eventsarray of OperationEventPresent on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first.
atrequiredstring (date-time)
kindrequiredstringFor example target_chosen, send_started, handed_over, undoing, cold_fallback, move_cancelled, recovery_started, succeeded, failed.
messagerequiredstring
datarequiredobject
created_atrequiredstring (date-time)
  • 401Not signed in, or the credential is invalid or expired.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 404No such resource in the caller's account.
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • defaultAny other error, usually 500.

Example

bash
curl 'https://cloud.ankra.app/v1/vpn-gateways/<id>' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

Rename a VPN gateway#

PATCH/v1/vpn-gateways/{id}
Operation
update_vpn_gateway
Credentials
API token, Portal session
Requires
Permission operate

Parameters

Parameters
NameInTypeDescription
idrequiredpathstring

Request bodyapplication/json

Request body fields
FieldTypeDescription
namerequiredstring

Responses

200The renamed VPN gateway.application/json

200 response fields
FieldTypeDescription
vpn_gatewayrequiredVpnGateway
idrequiredstring
zonerequiredstring
namerequiredstring
planrequiredstring
staterequiredstringOne of creating, running, error, deleting
moderequiredstringOne of wireguard, headscale
hostnamerequiredstring | nullA headscale gateway's DNS name; point it at public_ipv4 and public_ipv6.
login_serverrequiredstring | nullWhat Tailscale clients log in to (https://<hostname>); null for wireguard.
network_idsrequiredarray of string
networksrequiredarray of VpnGatewayNetworkEmpty in lists.
idrequiredstring
namerequiredstring
cidrrequiredstringThe network's IPv4 subnet, routed to the peers.
addressrequiredstring | nullThe gateway's own address on the network, where VPN traffic comes from. Null in lists and until placed.
tunnel_networkrequiredstring
tunnel_addressrequiredstringThe gateway's own address in the tunnel network.
listen_portrequiredinteger
public_ipv4requiredstring | null
public_ipv6requiredstring | null
endpointrequiredstring | nullWhat peers dial: <ipv4>:51820, or [<ipv6>]:51820 without the IPv4 add-on. Null in lists and until placed.
public_keyrequiredstring | nullThe gateway's WireGuard public key, generated on its VM. Null in lists and until the gateway reported it.
peer_countrequiredinteger
is_healthyrequiredbooleanFalse in lists.
health_detailrequiredstringEmpty in lists.
configuration_generationrequiredinteger
dnsrequiredVpnGatewayDns | nullA headscale gateway's last step, on GET /v1/vpn-gateways/{id} once the gateway holds its addresses: the records to create for its hostname at your DNS provider and whether the name resolves to them now (checked at most every 30 s). Devices join once it does. Null for a wireguard gateway, in lists and before the gateway has addresses.
hostnamerequiredstring
recordsrequiredarray of object
typerequiredstringOne of A, AAAA
namerequiredstring
valuerequiredstring
is_readyrequiredbooleanThe hostname resolves to every record's address.
instructionsrequiredstringWhat to do, in one sentence for a person.
problemrequiredstring | nullWhy the name is not ready; null when it is.
active_operationrequiredOperation | null
idrequiredstring
kindrequiredstringOne of server.create, server.metadata, server.start, server.stop, server.restart, server.delete, server.force_release, server.network_quarantine, server.network_release, server.change_plan, server.rebuild, server.renumber_ipv6, server.renumber_ipv4, server.provider_router_resize, server.add_public_ipv4, server.remove_public_ipv4, server.settle_public_ipv4, server.attach_network, server.detach_network, server.firewall, storage.create, storage.attach, storage.detach, storage.resize, storage.delete, storage.backup, backup.restore, backup.delete, template.create, template.copy, template.delete, snapshot.create, snapshot.delete, router.sync, floating_ip.sync, network.sync, public_pool.sync, zone.topology_sync, server.move, server.migrate, server.recover, server.settle_migration, node.cordon, node.uncordon, node.drain, node.fence, node.maintenance, node.agent_upgrade, node.retire, node.withdraw_retirement, node.provision, load_balancer.create, load_balancer.delete, database.create, database.delete, database.restore, database.change_plan, database.start, database.resize, edge.sync, edge.delete, vpn_gateway.sync, vpn_gateway.delete, storage.move, storage.rebalance_policy, storage.drain_host, object_storage.migrate, object_storage.migrate_zone, object_storage.cut_over_zone, kubernetes_cluster.create, kubernetes_cluster.delete, kubernetes_cluster.upgrade, kubernetes_cluster.snapshot, kubernetes_cluster.restore, node_pool.sync, node_pool.delete, kubernetes_host.bootstrap, kubernetes_host.scale, kubernetes_cluster.platform_register, kubernetes_cluster.platform_deregister, control_plane.expand, control_plane.shrink, backup.verify
server_idrequiredstring | null
storage_idrequiredstring | null
backup_idrequiredstring | null
template_idrequiredstring | null
router_idrequiredstring | null
floating_ip_idrequiredstring | null
node_idstringSet on node maintenance operations (operator only); absent otherwise.
load_balancer_idstring | nullSet on the operations that create and delete a load balancer.
database_idstring | nullSet on the operations that create and delete a managed database.
edge_idstring | nullSet on the operations that sync and delete a network edge.
vpn_gateway_idstring | nullSet on the operations that sync and delete a VPN gateway.
snapshot_idstring | nullSet on the operations that create and delete a snapshot, and on a storage.create that clones one.
kubernetes_cluster_idstring | nullSet on the operations of a managed Kubernetes cluster.
node_pool_idstring | nullSet on the operations of a Kubernetes node pool.
kubernetes_host_idstringSet on a regional host cluster bootstrap (operator only); absent otherwise.
statusrequiredstringOne of pending, running, succeeded, failed, cancelled
steprequiredstringMachine name of the current step, e.g. create_disk or transfer_cross_zone.
step_indexrequiredinteger
step_countrequiredinteger
errorrequiredstringEmpty unless the operation failed.
created_atrequiredstring (date-time)
started_atrequiredstring (date-time) | null
finished_atrequiredstring (date-time) | null
deadline_atrequiredstring (date-time)
actorstringWho asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations.
progressMigrationProgressPresent on GET /v1/operations/{id} while a server.migrate drives a live transfer.
staterequiredstringOne of reserved, detached, preparing, sending, switched, aborting
source_node_idrequiredstring
target_node_idrequiredstring
phaserequiredstringHow far the nodes report the current attempt.One of , preparing, transferring, completed, failed
attemptrequiredintegerWhich send this is under the convergence policy, from 1.
iterationrequiredintegerMemory passes so far in the current attempt.
transferred_bytesrequiredinteger
total_bytesrequiredinteger0 when the hypervisor does not report it.
dirty_bytes_per_secondrequiredinteger
downtime_millisecondsrequiredintegerThe pause the guest took at handover, once completed.
detailrequiredstring
reported_atrequiredstring (date-time) | nullThe reporting node's clock.
eventsarray of OperationEventPresent on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first.
atrequiredstring (date-time)
kindrequiredstringFor example target_chosen, send_started, handed_over, undoing, cold_fallback, move_cancelled, recovery_started, succeeded, failed.
messagerequiredstring
datarequiredobject
created_atrequiredstring (date-time)
  • 400The request is invalid; detail says why.
  • 401Not signed in, or the credential is invalid or expired.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 404No such resource in the caller's account.
  • 409The resource's state does not allow this now.
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • defaultAny other error, usually 500.

Example

bash
curl -X PATCH 'https://cloud.ankra.app/v1/vpn-gateways/<id>' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "string"
}'

Delete a VPN gateway, its VM and its peers#

DELETE/v1/vpn-gateways/{id}
Operation
delete_vpn_gateway
Credentials
API token, Portal session
Requires
Permission operate

Parameters

Parameters
NameInTypeDescription
idrequiredpathstring

Responses

202Accepted; poll the operation.application/json · OperationEnvelope

202 response fields
FieldTypeDescription
operationrequiredOperation
idrequiredstring
kindrequiredstringOne of server.create, server.metadata, server.start, server.stop, server.restart, server.delete, server.force_release, server.network_quarantine, server.network_release, server.change_plan, server.rebuild, server.renumber_ipv6, server.renumber_ipv4, server.provider_router_resize, server.add_public_ipv4, server.remove_public_ipv4, server.settle_public_ipv4, server.attach_network, server.detach_network, server.firewall, storage.create, storage.attach, storage.detach, storage.resize, storage.delete, storage.backup, backup.restore, backup.delete, template.create, template.copy, template.delete, snapshot.create, snapshot.delete, router.sync, floating_ip.sync, network.sync, public_pool.sync, zone.topology_sync, server.move, server.migrate, server.recover, server.settle_migration, node.cordon, node.uncordon, node.drain, node.fence, node.maintenance, node.agent_upgrade, node.retire, node.withdraw_retirement, node.provision, load_balancer.create, load_balancer.delete, database.create, database.delete, database.restore, database.change_plan, database.start, database.resize, edge.sync, edge.delete, vpn_gateway.sync, vpn_gateway.delete, storage.move, storage.rebalance_policy, storage.drain_host, object_storage.migrate, object_storage.migrate_zone, object_storage.cut_over_zone, kubernetes_cluster.create, kubernetes_cluster.delete, kubernetes_cluster.upgrade, kubernetes_cluster.snapshot, kubernetes_cluster.restore, node_pool.sync, node_pool.delete, kubernetes_host.bootstrap, kubernetes_host.scale, kubernetes_cluster.platform_register, kubernetes_cluster.platform_deregister, control_plane.expand, control_plane.shrink, backup.verify
server_idrequiredstring | null
storage_idrequiredstring | null
backup_idrequiredstring | null
template_idrequiredstring | null
router_idrequiredstring | null
floating_ip_idrequiredstring | null
node_idstringSet on node maintenance operations (operator only); absent otherwise.
load_balancer_idstring | nullSet on the operations that create and delete a load balancer.
database_idstring | nullSet on the operations that create and delete a managed database.
edge_idstring | nullSet on the operations that sync and delete a network edge.
vpn_gateway_idstring | nullSet on the operations that sync and delete a VPN gateway.
snapshot_idstring | nullSet on the operations that create and delete a snapshot, and on a storage.create that clones one.
kubernetes_cluster_idstring | nullSet on the operations of a managed Kubernetes cluster.
node_pool_idstring | nullSet on the operations of a Kubernetes node pool.
kubernetes_host_idstringSet on a regional host cluster bootstrap (operator only); absent otherwise.
statusrequiredstringOne of pending, running, succeeded, failed, cancelled
steprequiredstringMachine name of the current step, e.g. create_disk or transfer_cross_zone.
step_indexrequiredinteger
step_countrequiredinteger
errorrequiredstringEmpty unless the operation failed.
created_atrequiredstring (date-time)
started_atrequiredstring (date-time) | null
finished_atrequiredstring (date-time) | null
deadline_atrequiredstring (date-time)
actorstringWho asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations.
progressMigrationProgressPresent on GET /v1/operations/{id} while a server.migrate drives a live transfer.
staterequiredstringOne of reserved, detached, preparing, sending, switched, aborting
source_node_idrequiredstring
target_node_idrequiredstring
phaserequiredstringHow far the nodes report the current attempt.One of , preparing, transferring, completed, failed
attemptrequiredintegerWhich send this is under the convergence policy, from 1.
iterationrequiredintegerMemory passes so far in the current attempt.
transferred_bytesrequiredinteger
total_bytesrequiredinteger0 when the hypervisor does not report it.
dirty_bytes_per_secondrequiredinteger
downtime_millisecondsrequiredintegerThe pause the guest took at handover, once completed.
detailrequiredstring
reported_atrequiredstring (date-time) | nullThe reporting node's clock.
eventsarray of OperationEventPresent on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first.
atrequiredstring (date-time)
kindrequiredstringFor example target_chosen, send_started, handed_over, undoing, cold_fallback, move_cancelled, recovery_started, succeeded, failed.
messagerequiredstring
datarequiredobject
  • 401Not signed in, or the credential is invalid or expired.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 404No such resource in the caller's account.
  • 409The resource's state does not allow this now.
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • defaultAny other error, usually 500.

Example

bash
curl -X DELETE 'https://cloud.ankra.app/v1/vpn-gateways/<id>' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

Create a pre-auth key devices join a headscale gateway with#

POST/v1/vpn-gateways/{id}/auth-keys
Operation
create_vpn_gateway_auth_key
Credentials
API token, Portal session
Requires
Permission operate

Headscale gateways only (409 for a wireguard one, and while the gateway is not running). The key is in this answer only: Ankra keeps no copy and the audit event does not hold it. By default the key is for the caller's own devices, which then belong to the caller's user on the tailnet (user, their email); shared: true makes one for the shared user instead, for servers and CI. A reusable key joins many devices, an ephemeral one joins devices that are removed again when they go offline. install has the command to paste on Linux, macOS and Windows, and the steps on phones, which sign in without the key and show a code to register with POST /v1/vpn-gateways/{id}/devices.

Parameters

Parameters
NameInTypeDescription
idrequiredpathstring

Request bodyapplication/json

Request body fields
FieldTypeDescription
sharedbooleanA key of the shared user (servers, CI) instead of one for your own devices.
reusableboolean
ephemeralboolean
expiration_hoursintegerHow long the key may be used to join; joined devices stay.

Responses

201The key, shown once.application/json

201 response fields
FieldTypeDescription
auth_keyrequiredVpnGatewayAuthKey
keyrequiredstring
expires_atrequiredstring (date-time)
reusablerequiredboolean
ephemeralrequiredboolean
userrequiredstringThe tailnet user the key's devices belong to: your email, or devices for a shared key.
login_serverrequiredstring
installrequiredarray of objectOne entry per platform, in the order linux, macos, windows, ios, android.
platformrequiredstringOne of linux, macos, windows, ios, android
titlerequiredstring
commandrequiredstring | nullOne command to paste, with the key in it; null on phones.
stepsrequiredarray of string
uses_registration_coderequiredbooleanThe device signs in without the key and shows a code to register with POST /v1/vpn-gateways/{id}/devices.
join_commandrequiredstringThe Linux command line: sudo tailscale up --login-server=… --authkey=… --accept-routes.
  • 400The request is invalid; detail says why.
  • 401Not signed in, or the credential is invalid or expired.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 404No such resource in the caller's account.
  • 409The resource's state does not allow this now.
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • defaultAny other error, usually 500.

Example

bash
curl -X POST 'https://cloud.ankra.app/v1/vpn-gateways/<id>/auth-keys' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "shared": false,
  "reusable": false,
  "ephemeral": false,
  "expiration_hours": 24
}'

List the devices of a headscale gateway's tailnet#

GET/v1/vpn-gateways/{id}/devices
Operation
list_vpn_gateway_devices
Credentials
API token, Portal session
Requires
Permission read

Headscale gateways only (409 for a wireguard one, and while the gateway is not running). The gateway's own node is not listed.

Parameters

Parameters
NameInTypeDescription
idrequiredpathstring

Responses

200The devices.application/json

200 response fields
FieldTypeDescription
itemsrequiredarray of VpnGatewayDevice
idrequiredstring
namerequiredstring
userrequiredstringThe tailnet user the device belongs to: a person's email, or devices for shared ones.
is_minerequiredbooleanThe device belongs to the caller.
addressesrequiredarray of stringTailnet addresses.
onlinerequiredboolean
last_seen_atrequiredstring (date-time) | null
created_atrequiredstring (date-time) | null
  • 401Not signed in, or the credential is invalid or expired.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 404No such resource in the caller's account.
  • 409The resource's state does not allow this now.
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • defaultAny other error, usually 500.

Example

bash
curl 'https://cloud.ankra.app/v1/vpn-gateways/<id>/devices' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

Register a phone that signed in to a headscale gateway, for you#

POST/v1/vpn-gateways/{id}/devices
Operation
register_vpn_gateway_device
Credentials
API token, Portal session
Requires
Permission operate

The Tailscale apps on iPhone, iPad and Android sign in to the gateway's login server without a key and show a code. Pasting it here registers the device for the caller's own user on the tailnet. Headscale gateways only (409 for a wireguard one, and while the gateway is not running).

Parameters

Parameters
NameInTypeDescription
idrequiredpathstring

Request bodyapplication/json

Request body fields
FieldTypeDescription
registration_keyrequiredstringThe code the app shows after signing in.

Responses

201The registered device.application/json

201 response fields
FieldTypeDescription
devicerequiredVpnGatewayDevice
idrequiredstring
namerequiredstring
userrequiredstringThe tailnet user the device belongs to: a person's email, or devices for shared ones.
is_minerequiredbooleanThe device belongs to the caller.
addressesrequiredarray of stringTailnet addresses.
onlinerequiredboolean
last_seen_atrequiredstring (date-time) | null
created_atrequiredstring (date-time) | null
  • 400The request is invalid; detail says why.
  • 401Not signed in, or the credential is invalid or expired.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 404No such resource in the caller's account.
  • 409The resource's state does not allow this now.
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • defaultAny other error, usually 500.

Example

bash
curl -X POST 'https://cloud.ankra.app/v1/vpn-gateways/<id>/devices' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "registration_key": "string"
}'

Remove a device from a headscale gateway's tailnet#

DELETE/v1/vpn-gateways/{id}/devices/{device}
Operation
delete_vpn_gateway_device
Credentials
API token, Portal session
Requires
Permission operate

The device is logged out; it joins again only with a new key.

Parameters

Parameters
NameInTypeDescription
idrequiredpathstring
devicerequiredpathstringThe device's id.

Responses

204The device was removed.

  • 401Not signed in, or the credential is invalid or expired.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 404No such resource in the caller's account.
  • 409The resource's state does not allow this now.
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • defaultAny other error, usually 500.

Example

bash
curl -X DELETE 'https://cloud.ankra.app/v1/vpn-gateways/<id>/devices/<device>' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

List a VPN gateway's peers#

GET/v1/vpn-gateways/{id}/peers
Operation
list_vpn_gateway_peers
Credentials
API token, Portal session
Requires
Permission read

Parameters

Parameters
NameInTypeDescription
idrequiredpathstring

Responses

200Every peer of the gateway, by name.application/json

200 response fields
FieldTypeDescription
itemsrequiredarray of VpnGatewayPeer
idrequiredstring
namerequiredstring
kindrequiredstringOne of client, site
public_keyrequiredstring
tunnel_addressrequiredstringThe peer's address in the gateway's tunnel network.
remote_networksrequiredarray of string
endpointrequiredstring | null
persistent_keepalive_secondsrequiredinteger
owner_user_idrequiredstring | nullThe user who added the peer for a device of their own.
is_minerequiredbooleanThe peer is a device of the caller.
created_atrequiredstring (date-time)
  • 401Not signed in, or the credential is invalid or expired.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 404No such resource in the caller's account.
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • defaultAny other error, usually 500.

Example

bash
curl 'https://cloud.ankra.app/v1/vpn-gateways/<id>/peers' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

Add a client device or a remote site to a VPN gateway#

POST/v1/vpn-gateways/{id}/peers
Operation
create_vpn_gateway_peer
Credentials
API token, Portal session
Requires
Permission operate

The peer is named by its WireGuard public key; its private key never reaches Ankra (generate the pair with wg genkey | tee peer.key | wg pubkey, or let the console generate it in the browser). The peer gets the next free address of the gateway's tunnel network. A site peer also routes remote_networks, the networks behind it, which then reach the gateway's private networks too; give it an endpoint when the gateway should be able to reach it first. Applied by one vpn_gateway.sync operation without dropping the other peers' sessions.

Parameters

Parameters
NameInTypeDescription
idrequiredpathstring

Request bodyapplication/json · CreateVpnGatewayPeerRequest

Request body fields
FieldTypeDescription
namerequiredstring
kindstringOne of client, site
public_keyrequiredstringThe peer's WireGuard public key (44 characters of base64).
remote_networksarray of stringA site's IPv4 networks (CIDR) behind it; not for a client.
endpointstringWhere the gateway can reach the peer, <ipv4>:<port> or [<ipv6>]:<port>; leave it out for a peer that roams.
persistent_keepalive_secondsintegerKeepalives the gateway sends the peer, for a site behind NAT that the gateway must reach first.
minebooleanA client peer for a device of your own: it is listed as yours.

Responses

202The peer and the vpn_gateway.sync operation that applies it.application/json

202 response fields
FieldTypeDescription
peerrequiredVpnGatewayPeer
idrequiredstring
namerequiredstring
kindrequiredstringOne of client, site
public_keyrequiredstring
tunnel_addressrequiredstringThe peer's address in the gateway's tunnel network.
remote_networksrequiredarray of string
endpointrequiredstring | null
persistent_keepalive_secondsrequiredinteger
owner_user_idrequiredstring | nullThe user who added the peer for a device of their own.
is_minerequiredbooleanThe peer is a device of the caller.
created_atrequiredstring (date-time)
operationrequiredOperation
idrequiredstring
kindrequiredstringOne of server.create, server.metadata, server.start, server.stop, server.restart, server.delete, server.force_release, server.network_quarantine, server.network_release, server.change_plan, server.rebuild, server.renumber_ipv6, server.renumber_ipv4, server.provider_router_resize, server.add_public_ipv4, server.remove_public_ipv4, server.settle_public_ipv4, server.attach_network, server.detach_network, server.firewall, storage.create, storage.attach, storage.detach, storage.resize, storage.delete, storage.backup, backup.restore, backup.delete, template.create, template.copy, template.delete, snapshot.create, snapshot.delete, router.sync, floating_ip.sync, network.sync, public_pool.sync, zone.topology_sync, server.move, server.migrate, server.recover, server.settle_migration, node.cordon, node.uncordon, node.drain, node.fence, node.maintenance, node.agent_upgrade, node.retire, node.withdraw_retirement, node.provision, load_balancer.create, load_balancer.delete, database.create, database.delete, database.restore, database.change_plan, database.start, database.resize, edge.sync, edge.delete, vpn_gateway.sync, vpn_gateway.delete, storage.move, storage.rebalance_policy, storage.drain_host, object_storage.migrate, object_storage.migrate_zone, object_storage.cut_over_zone, kubernetes_cluster.create, kubernetes_cluster.delete, kubernetes_cluster.upgrade, kubernetes_cluster.snapshot, kubernetes_cluster.restore, node_pool.sync, node_pool.delete, kubernetes_host.bootstrap, kubernetes_host.scale, kubernetes_cluster.platform_register, kubernetes_cluster.platform_deregister, control_plane.expand, control_plane.shrink, backup.verify
server_idrequiredstring | null
storage_idrequiredstring | null
backup_idrequiredstring | null
template_idrequiredstring | null
router_idrequiredstring | null
floating_ip_idrequiredstring | null
node_idstringSet on node maintenance operations (operator only); absent otherwise.
load_balancer_idstring | nullSet on the operations that create and delete a load balancer.
database_idstring | nullSet on the operations that create and delete a managed database.
edge_idstring | nullSet on the operations that sync and delete a network edge.
vpn_gateway_idstring | nullSet on the operations that sync and delete a VPN gateway.
snapshot_idstring | nullSet on the operations that create and delete a snapshot, and on a storage.create that clones one.
kubernetes_cluster_idstring | nullSet on the operations of a managed Kubernetes cluster.
node_pool_idstring | nullSet on the operations of a Kubernetes node pool.
kubernetes_host_idstringSet on a regional host cluster bootstrap (operator only); absent otherwise.
statusrequiredstringOne of pending, running, succeeded, failed, cancelled
steprequiredstringMachine name of the current step, e.g. create_disk or transfer_cross_zone.
step_indexrequiredinteger
step_countrequiredinteger
errorrequiredstringEmpty unless the operation failed.
created_atrequiredstring (date-time)
started_atrequiredstring (date-time) | null
finished_atrequiredstring (date-time) | null
deadline_atrequiredstring (date-time)
actorstringWho asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations.
progressMigrationProgressPresent on GET /v1/operations/{id} while a server.migrate drives a live transfer.
staterequiredstringOne of reserved, detached, preparing, sending, switched, aborting
source_node_idrequiredstring
target_node_idrequiredstring
phaserequiredstringHow far the nodes report the current attempt.One of , preparing, transferring, completed, failed
attemptrequiredintegerWhich send this is under the convergence policy, from 1.
iterationrequiredintegerMemory passes so far in the current attempt.
transferred_bytesrequiredinteger
total_bytesrequiredinteger0 when the hypervisor does not report it.
dirty_bytes_per_secondrequiredinteger
downtime_millisecondsrequiredintegerThe pause the guest took at handover, once completed.
detailrequiredstring
reported_atrequiredstring (date-time) | nullThe reporting node's clock.
eventsarray of OperationEventPresent on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first.
atrequiredstring (date-time)
kindrequiredstringFor example target_chosen, send_started, handed_over, undoing, cold_fallback, move_cancelled, recovery_started, succeeded, failed.
messagerequiredstring
datarequiredobject
  • 400The request is invalid; detail says why.
  • 401Not signed in, or the credential is invalid or expired.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 404No such resource in the caller's account.
  • 409The resource's state does not allow this now.
  • 422The account would exceed a quota; detail names the limit and reason is quota_exceeded.
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • defaultAny other error, usually 500.

Example

bash
curl -X POST 'https://cloud.ankra.app/v1/vpn-gateways/<id>/peers' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "string",
  "public_key": "string"
}'

Remove a peer from a VPN gateway#

DELETE/v1/vpn-gateways/{id}/peers/{peer}
Operation
delete_vpn_gateway_peer
Credentials
API token, Portal session
Requires
Permission operate

Parameters

Parameters
NameInTypeDescription
idrequiredpathstring
peerrequiredpathstringThe peer's id.

Responses

202Accepted; poll the operation.application/json · OperationEnvelope

202 response fields
FieldTypeDescription
operationrequiredOperation
idrequiredstring
kindrequiredstringOne of server.create, server.metadata, server.start, server.stop, server.restart, server.delete, server.force_release, server.network_quarantine, server.network_release, server.change_plan, server.rebuild, server.renumber_ipv6, server.renumber_ipv4, server.provider_router_resize, server.add_public_ipv4, server.remove_public_ipv4, server.settle_public_ipv4, server.attach_network, server.detach_network, server.firewall, storage.create, storage.attach, storage.detach, storage.resize, storage.delete, storage.backup, backup.restore, backup.delete, template.create, template.copy, template.delete, snapshot.create, snapshot.delete, router.sync, floating_ip.sync, network.sync, public_pool.sync, zone.topology_sync, server.move, server.migrate, server.recover, server.settle_migration, node.cordon, node.uncordon, node.drain, node.fence, node.maintenance, node.agent_upgrade, node.retire, node.withdraw_retirement, node.provision, load_balancer.create, load_balancer.delete, database.create, database.delete, database.restore, database.change_plan, database.start, database.resize, edge.sync, edge.delete, vpn_gateway.sync, vpn_gateway.delete, storage.move, storage.rebalance_policy, storage.drain_host, object_storage.migrate, object_storage.migrate_zone, object_storage.cut_over_zone, kubernetes_cluster.create, kubernetes_cluster.delete, kubernetes_cluster.upgrade, kubernetes_cluster.snapshot, kubernetes_cluster.restore, node_pool.sync, node_pool.delete, kubernetes_host.bootstrap, kubernetes_host.scale, kubernetes_cluster.platform_register, kubernetes_cluster.platform_deregister, control_plane.expand, control_plane.shrink, backup.verify
server_idrequiredstring | null
storage_idrequiredstring | null
backup_idrequiredstring | null
template_idrequiredstring | null
router_idrequiredstring | null
floating_ip_idrequiredstring | null
node_idstringSet on node maintenance operations (operator only); absent otherwise.
load_balancer_idstring | nullSet on the operations that create and delete a load balancer.
database_idstring | nullSet on the operations that create and delete a managed database.
edge_idstring | nullSet on the operations that sync and delete a network edge.
vpn_gateway_idstring | nullSet on the operations that sync and delete a VPN gateway.
snapshot_idstring | nullSet on the operations that create and delete a snapshot, and on a storage.create that clones one.
kubernetes_cluster_idstring | nullSet on the operations of a managed Kubernetes cluster.
node_pool_idstring | nullSet on the operations of a Kubernetes node pool.
kubernetes_host_idstringSet on a regional host cluster bootstrap (operator only); absent otherwise.
statusrequiredstringOne of pending, running, succeeded, failed, cancelled
steprequiredstringMachine name of the current step, e.g. create_disk or transfer_cross_zone.
step_indexrequiredinteger
step_countrequiredinteger
errorrequiredstringEmpty unless the operation failed.
created_atrequiredstring (date-time)
started_atrequiredstring (date-time) | null
finished_atrequiredstring (date-time) | null
deadline_atrequiredstring (date-time)
actorstringWho asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations.
progressMigrationProgressPresent on GET /v1/operations/{id} while a server.migrate drives a live transfer.
staterequiredstringOne of reserved, detached, preparing, sending, switched, aborting
source_node_idrequiredstring
target_node_idrequiredstring
phaserequiredstringHow far the nodes report the current attempt.One of , preparing, transferring, completed, failed
attemptrequiredintegerWhich send this is under the convergence policy, from 1.
iterationrequiredintegerMemory passes so far in the current attempt.
transferred_bytesrequiredinteger
total_bytesrequiredinteger0 when the hypervisor does not report it.
dirty_bytes_per_secondrequiredinteger
downtime_millisecondsrequiredintegerThe pause the guest took at handover, once completed.
detailrequiredstring
reported_atrequiredstring (date-time) | nullThe reporting node's clock.
eventsarray of OperationEventPresent on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first.
atrequiredstring (date-time)
kindrequiredstringFor example target_chosen, send_started, handed_over, undoing, cold_fallback, move_cancelled, recovery_started, succeeded, failed.
messagerequiredstring
datarequiredobject
  • 401Not signed in, or the credential is invalid or expired.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 404No such resource in the caller's account.
  • 409The resource's state does not allow this now.
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • defaultAny other error, usually 500.

Example

bash
curl -X DELETE 'https://cloud.ankra.app/v1/vpn-gateways/<id>/peers/<peer>' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

Get a peer's wg-quick configuration#

GET/v1/vpn-gateways/{id}/peers/{peer}/configuration
Operation
get_vpn_gateway_peer_configuration
Credentials
API token, Portal session
Requires
Permission read

A wg-quick file for the peer: its tunnel address, the gateway's public key and endpoint, and every network of the gateway as AllowedIPs. The PrivateKey line holds the placeholder private_key_placeholder; replace it with the peer's own private key, which Ankra never has. 409 until the gateway has generated its key.

Parameters

Parameters
NameInTypeDescription
idrequiredpathstring
peerrequiredpathstringThe peer's id.

Responses

200The configuration.application/json

200 response fields
FieldTypeDescription
configurationrequiredstring
filenamerequiredstringA file name for it, e.g. office.conf: wg-quick names the interface after it.
private_key_placeholderrequiredstring
  • 401Not signed in, or the credential is invalid or expired.
  • 403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
  • 404No such resource in the caller's account.
  • 409The resource's state does not allow this now.
  • 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
  • defaultAny other error, usually 500.

Example

bash
curl 'https://cloud.ankra.app/v1/vpn-gateways/<id>/peers/<peer>/configuration' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"