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#
/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
| Name | In | Type | Description |
|---|---|---|---|
cursor | query | string | The next_cursor of the previous page. |
limit | query | integer | Page size; the server applies its default and maximum. |
Responses
200A page of VPN gateways, newest first.application/json
| Field | Type | Description |
|---|---|---|
itemsrequired | array of VpnGateway | |
idrequired | string | |
zonerequired | string | |
namerequired | string | |
planrequired | string | |
staterequired | string | One of creating, running, error, deleting |
moderequired | string | One of wireguard, headscale |
hostnamerequired | string | null | A headscale gateway's DNS name; point it at public_ipv4 and public_ipv6. |
login_serverrequired | string | null | What Tailscale clients log in to (https://<hostname>); null for wireguard. |
network_idsrequired | array of string | |
networksrequired | array of VpnGatewayNetwork | Empty in lists. |
idrequired | string | |
namerequired | string | |
cidrrequired | string | The network's IPv4 subnet, routed to the peers. |
addressrequired | string | null | The gateway's own address on the network, where VPN traffic comes from. Null in lists and until placed. |
tunnel_networkrequired | string | |
tunnel_addressrequired | string | The gateway's own address in the tunnel network. |
listen_portrequired | integer | |
public_ipv4required | string | null | |
public_ipv6required | string | null | |
endpointrequired | string | null | What peers dial: <ipv4>:51820, or [<ipv6>]:51820 without the IPv4 add-on. Null in lists and until placed. |
public_keyrequired | string | null | The gateway's WireGuard public key, generated on its VM. Null in lists and until the gateway reported it. |
peer_countrequired | integer | |
is_healthyrequired | boolean | False in lists. |
health_detailrequired | string | Empty in lists. |
configuration_generationrequired | integer | |
dnsrequired | VpnGatewayDns | null | A 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. |
hostnamerequired | string | |
recordsrequired | array of object | |
typerequired | string | One of A, AAAA |
namerequired | string | |
valuerequired | string | |
is_readyrequired | boolean | The hostname resolves to every record's address. |
instructionsrequired | string | What to do, in one sentence for a person. |
problemrequired | string | null | Why the name is not ready; null when it is. |
active_operationrequired | Operation | null | |
idrequired | string | |
kindrequired | string | One 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_idrequired | string | null | |
storage_idrequired | string | null | |
backup_idrequired | string | null | |
template_idrequired | string | null | |
router_idrequired | string | null | |
floating_ip_idrequired | string | null | |
node_id | string | Set on node maintenance operations (operator only); absent otherwise. |
load_balancer_id | string | null | Set on the operations that create and delete a load balancer. |
database_id | string | null | Set on the operations that create and delete a managed database. |
edge_id | string | null | Set on the operations that sync and delete a network edge. |
vpn_gateway_id | string | null | Set on the operations that sync and delete a VPN gateway. |
snapshot_id | string | null | Set on the operations that create and delete a snapshot, and on a storage.create that clones one. |
kubernetes_cluster_id | string | null | Set on the operations of a managed Kubernetes cluster. |
node_pool_id | string | null | Set on the operations of a Kubernetes node pool. |
kubernetes_host_id | string | Set on a regional host cluster bootstrap (operator only); absent otherwise. |
statusrequired | string | One of pending, running, succeeded, failed, cancelled |
steprequired | string | Machine name of the current step, e.g. create_disk or transfer_cross_zone. |
step_indexrequired | integer | |
step_countrequired | integer | |
errorrequired | string | Empty unless the operation failed. |
created_atrequired | string (date-time) | |
started_atrequired | string (date-time) | null | |
finished_atrequired | string (date-time) | null | |
deadline_atrequired | string (date-time) | |
actor | string | Who asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations. |
progress | MigrationProgress | Present on GET /v1/operations/{id} while a server.migrate drives a live transfer. |
staterequired | string | One of reserved, detached, preparing, sending, switched, aborting |
source_node_idrequired | string | |
target_node_idrequired | string | |
phaserequired | string | How far the nodes report the current attempt.One of , preparing, transferring, completed, failed |
attemptrequired | integer | Which send this is under the convergence policy, from 1. |
iterationrequired | integer | Memory passes so far in the current attempt. |
transferred_bytesrequired | integer | |
total_bytesrequired | integer | 0 when the hypervisor does not report it. |
dirty_bytes_per_secondrequired | integer | |
downtime_millisecondsrequired | integer | The pause the guest took at handover, once completed. |
detailrequired | string | |
reported_atrequired | string (date-time) | null | The reporting node's clock. |
events | array of OperationEvent | Present on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first. |
atrequired | string (date-time) | |
kindrequired | string | For example target_chosen, send_started, handed_over, undoing, cold_fallback, move_cancelled, recovery_started, succeeded, failed. |
messagerequired | string | |
datarequired | object | |
created_atrequired | string (date-time) | |
next_cursorrequired | string | null | Pass as ?cursor= for the next page; null on the last page. |
- 400The request is invalid;
detailsays 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_credentialson 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
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#
/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; onlypublic_keyleaves it.headscale: a Headscale control server forhostname, a DNS name you point at the gateway's addresses (A topublic_ipv4, AAAA topublic_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
| Name | In | Type | Description |
|---|---|---|---|
Idempotency-Key | header | string | A 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
| Field | Type | Description |
|---|---|---|
network_idsrequired | array of string | The private networks the gateway reaches, all in one zone; the gateway runs in that zone. |
name | string | Defaults to "<first network name> VPN". |
plan | string | |
tunnel_network | string | The 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_ipv4 | boolean | Give the gateway the public IPv4 add-on, so peers on IPv4-only networks reach it; without it peers connect over IPv6. |
mode | string | One of wireguard, headscale |
hostname | string | Headscale 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
| Field | Type | Description |
|---|---|---|
vpn_gatewayrequired | VpnGateway | |
idrequired | string | |
zonerequired | string | |
namerequired | string | |
planrequired | string | |
staterequired | string | One of creating, running, error, deleting |
moderequired | string | One of wireguard, headscale |
hostnamerequired | string | null | A headscale gateway's DNS name; point it at public_ipv4 and public_ipv6. |
login_serverrequired | string | null | What Tailscale clients log in to (https://<hostname>); null for wireguard. |
network_idsrequired | array of string | |
networksrequired | array of VpnGatewayNetwork | Empty in lists. |
idrequired | string | |
namerequired | string | |
cidrrequired | string | The network's IPv4 subnet, routed to the peers. |
addressrequired | string | null | The gateway's own address on the network, where VPN traffic comes from. Null in lists and until placed. |
tunnel_networkrequired | string | |
tunnel_addressrequired | string | The gateway's own address in the tunnel network. |
listen_portrequired | integer | |
public_ipv4required | string | null | |
public_ipv6required | string | null | |
endpointrequired | string | null | What peers dial: <ipv4>:51820, or [<ipv6>]:51820 without the IPv4 add-on. Null in lists and until placed. |
public_keyrequired | string | null | The gateway's WireGuard public key, generated on its VM. Null in lists and until the gateway reported it. |
peer_countrequired | integer | |
is_healthyrequired | boolean | False in lists. |
health_detailrequired | string | Empty in lists. |
configuration_generationrequired | integer | |
dnsrequired | VpnGatewayDns | null | A 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. |
hostnamerequired | string | |
recordsrequired | array of object | |
typerequired | string | One of A, AAAA |
namerequired | string | |
valuerequired | string | |
is_readyrequired | boolean | The hostname resolves to every record's address. |
instructionsrequired | string | What to do, in one sentence for a person. |
problemrequired | string | null | Why the name is not ready; null when it is. |
active_operationrequired | Operation | null | |
idrequired | string | |
kindrequired | string | One 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_idrequired | string | null | |
storage_idrequired | string | null | |
backup_idrequired | string | null | |
template_idrequired | string | null | |
router_idrequired | string | null | |
floating_ip_idrequired | string | null | |
node_id | string | Set on node maintenance operations (operator only); absent otherwise. |
load_balancer_id | string | null | Set on the operations that create and delete a load balancer. |
database_id | string | null | Set on the operations that create and delete a managed database. |
edge_id | string | null | Set on the operations that sync and delete a network edge. |
vpn_gateway_id | string | null | Set on the operations that sync and delete a VPN gateway. |
snapshot_id | string | null | Set on the operations that create and delete a snapshot, and on a storage.create that clones one. |
kubernetes_cluster_id | string | null | Set on the operations of a managed Kubernetes cluster. |
node_pool_id | string | null | Set on the operations of a Kubernetes node pool. |
kubernetes_host_id | string | Set on a regional host cluster bootstrap (operator only); absent otherwise. |
statusrequired | string | One of pending, running, succeeded, failed, cancelled |
steprequired | string | Machine name of the current step, e.g. create_disk or transfer_cross_zone. |
step_indexrequired | integer | |
step_countrequired | integer | |
errorrequired | string | Empty unless the operation failed. |
created_atrequired | string (date-time) | |
started_atrequired | string (date-time) | null | |
finished_atrequired | string (date-time) | null | |
deadline_atrequired | string (date-time) | |
actor | string | Who asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations. |
progress | MigrationProgress | Present on GET /v1/operations/{id} while a server.migrate drives a live transfer. |
staterequired | string | One of reserved, detached, preparing, sending, switched, aborting |
source_node_idrequired | string | |
target_node_idrequired | string | |
phaserequired | string | How far the nodes report the current attempt.One of , preparing, transferring, completed, failed |
attemptrequired | integer | Which send this is under the convergence policy, from 1. |
iterationrequired | integer | Memory passes so far in the current attempt. |
transferred_bytesrequired | integer | |
total_bytesrequired | integer | 0 when the hypervisor does not report it. |
dirty_bytes_per_secondrequired | integer | |
downtime_millisecondsrequired | integer | The pause the guest took at handover, once completed. |
detailrequired | string | |
reported_atrequired | string (date-time) | null | The reporting node's clock. |
events | array of OperationEvent | Present on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first. |
atrequired | string (date-time) | |
kindrequired | string | For example target_chosen, send_started, handed_over, undoing, cold_fallback, move_cancelled, recovery_started, succeeded, failed. |
messagerequired | string | |
datarequired | object | |
created_atrequired | string (date-time) | |
operationrequired | Operation | |
idrequired | string | |
kindrequired | string | One 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_idrequired | string | null | |
storage_idrequired | string | null | |
backup_idrequired | string | null | |
template_idrequired | string | null | |
router_idrequired | string | null | |
floating_ip_idrequired | string | null | |
node_id | string | Set on node maintenance operations (operator only); absent otherwise. |
load_balancer_id | string | null | Set on the operations that create and delete a load balancer. |
database_id | string | null | Set on the operations that create and delete a managed database. |
edge_id | string | null | Set on the operations that sync and delete a network edge. |
vpn_gateway_id | string | null | Set on the operations that sync and delete a VPN gateway. |
snapshot_id | string | null | Set on the operations that create and delete a snapshot, and on a storage.create that clones one. |
kubernetes_cluster_id | string | null | Set on the operations of a managed Kubernetes cluster. |
node_pool_id | string | null | Set on the operations of a Kubernetes node pool. |
kubernetes_host_id | string | Set on a regional host cluster bootstrap (operator only); absent otherwise. |
statusrequired | string | One of pending, running, succeeded, failed, cancelled |
steprequired | string | Machine name of the current step, e.g. create_disk or transfer_cross_zone. |
step_indexrequired | integer | |
step_countrequired | integer | |
errorrequired | string | Empty unless the operation failed. |
created_atrequired | string (date-time) | |
started_atrequired | string (date-time) | null | |
finished_atrequired | string (date-time) | null | |
deadline_atrequired | string (date-time) | |
actor | string | Who asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations. |
progress | MigrationProgress | Present on GET /v1/operations/{id} while a server.migrate drives a live transfer. |
staterequired | string | One of reserved, detached, preparing, sending, switched, aborting |
source_node_idrequired | string | |
target_node_idrequired | string | |
phaserequired | string | How far the nodes report the current attempt.One of , preparing, transferring, completed, failed |
attemptrequired | integer | Which send this is under the convergence policy, from 1. |
iterationrequired | integer | Memory passes so far in the current attempt. |
transferred_bytesrequired | integer | |
total_bytesrequired | integer | 0 when the hypervisor does not report it. |
dirty_bytes_per_secondrequired | integer | |
downtime_millisecondsrequired | integer | The pause the guest took at handover, once completed. |
detailrequired | string | |
reported_atrequired | string (date-time) | null | The reporting node's clock. |
events | array of OperationEvent | Present on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first. |
atrequired | string (date-time) | |
kindrequired | string | For example target_chosen, send_started, handed_over, undoing, cold_fallback, move_cancelled, recovery_started, succeeded, failed. |
messagerequired | string | |
datarequired | object |
- 400The request is invalid;
detailsays why. - 401Not signed in, or the credential is invalid or expired.
- 402The account may not create this.
reasonispayment_method_requiredwhile 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 throughPOST /v1/account/billing/setup-session, or free what the account no longer needs);owner_approval_requiredwhile its owner has not approved paid usage and no credit is left; oraccount_suspendedwhile an invoice is overdue past the grace period (pay it) or Ankra staff suspended the account (contact support). Aprepaidaccount (linked to an Ankra platform organisation) is refused withpayment_method_requiredwhile it has no card, and withcredit_requiredonce 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, andtop_up_urlnames that page when Cloud knows it.GET /v1/account/billingreports the samestanding. Forpayment_method_requiredandcredit_required,detailnames 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_credentialson 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;
detailnames the limit andreasonisquota_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 indetail), or a host did not answer; try another plan or zone, or try again later. - defaultAny other error, usually 500.
Example
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#
/v1/vpn-gateways/{id}- Operation
get_vpn_gateway- Credentials
- API token, Portal session
- Requires
- Permission
read
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
200The VPN gateway.application/json
| Field | Type | Description |
|---|---|---|
vpn_gatewayrequired | VpnGateway | |
idrequired | string | |
zonerequired | string | |
namerequired | string | |
planrequired | string | |
staterequired | string | One of creating, running, error, deleting |
moderequired | string | One of wireguard, headscale |
hostnamerequired | string | null | A headscale gateway's DNS name; point it at public_ipv4 and public_ipv6. |
login_serverrequired | string | null | What Tailscale clients log in to (https://<hostname>); null for wireguard. |
network_idsrequired | array of string | |
networksrequired | array of VpnGatewayNetwork | Empty in lists. |
idrequired | string | |
namerequired | string | |
cidrrequired | string | The network's IPv4 subnet, routed to the peers. |
addressrequired | string | null | The gateway's own address on the network, where VPN traffic comes from. Null in lists and until placed. |
tunnel_networkrequired | string | |
tunnel_addressrequired | string | The gateway's own address in the tunnel network. |
listen_portrequired | integer | |
public_ipv4required | string | null | |
public_ipv6required | string | null | |
endpointrequired | string | null | What peers dial: <ipv4>:51820, or [<ipv6>]:51820 without the IPv4 add-on. Null in lists and until placed. |
public_keyrequired | string | null | The gateway's WireGuard public key, generated on its VM. Null in lists and until the gateway reported it. |
peer_countrequired | integer | |
is_healthyrequired | boolean | False in lists. |
health_detailrequired | string | Empty in lists. |
configuration_generationrequired | integer | |
dnsrequired | VpnGatewayDns | null | A 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. |
hostnamerequired | string | |
recordsrequired | array of object | |
typerequired | string | One of A, AAAA |
namerequired | string | |
valuerequired | string | |
is_readyrequired | boolean | The hostname resolves to every record's address. |
instructionsrequired | string | What to do, in one sentence for a person. |
problemrequired | string | null | Why the name is not ready; null when it is. |
active_operationrequired | Operation | null | |
idrequired | string | |
kindrequired | string | One 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_idrequired | string | null | |
storage_idrequired | string | null | |
backup_idrequired | string | null | |
template_idrequired | string | null | |
router_idrequired | string | null | |
floating_ip_idrequired | string | null | |
node_id | string | Set on node maintenance operations (operator only); absent otherwise. |
load_balancer_id | string | null | Set on the operations that create and delete a load balancer. |
database_id | string | null | Set on the operations that create and delete a managed database. |
edge_id | string | null | Set on the operations that sync and delete a network edge. |
vpn_gateway_id | string | null | Set on the operations that sync and delete a VPN gateway. |
snapshot_id | string | null | Set on the operations that create and delete a snapshot, and on a storage.create that clones one. |
kubernetes_cluster_id | string | null | Set on the operations of a managed Kubernetes cluster. |
node_pool_id | string | null | Set on the operations of a Kubernetes node pool. |
kubernetes_host_id | string | Set on a regional host cluster bootstrap (operator only); absent otherwise. |
statusrequired | string | One of pending, running, succeeded, failed, cancelled |
steprequired | string | Machine name of the current step, e.g. create_disk or transfer_cross_zone. |
step_indexrequired | integer | |
step_countrequired | integer | |
errorrequired | string | Empty unless the operation failed. |
created_atrequired | string (date-time) | |
started_atrequired | string (date-time) | null | |
finished_atrequired | string (date-time) | null | |
deadline_atrequired | string (date-time) | |
actor | string | Who asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations. |
progress | MigrationProgress | Present on GET /v1/operations/{id} while a server.migrate drives a live transfer. |
staterequired | string | One of reserved, detached, preparing, sending, switched, aborting |
source_node_idrequired | string | |
target_node_idrequired | string | |
phaserequired | string | How far the nodes report the current attempt.One of , preparing, transferring, completed, failed |
attemptrequired | integer | Which send this is under the convergence policy, from 1. |
iterationrequired | integer | Memory passes so far in the current attempt. |
transferred_bytesrequired | integer | |
total_bytesrequired | integer | 0 when the hypervisor does not report it. |
dirty_bytes_per_secondrequired | integer | |
downtime_millisecondsrequired | integer | The pause the guest took at handover, once completed. |
detailrequired | string | |
reported_atrequired | string (date-time) | null | The reporting node's clock. |
events | array of OperationEvent | Present on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first. |
atrequired | string (date-time) | |
kindrequired | string | For example target_chosen, send_started, handed_over, undoing, cold_fallback, move_cancelled, recovery_started, succeeded, failed. |
messagerequired | string | |
datarequired | object | |
created_atrequired | string (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_credentialson 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
curl 'https://cloud.ankra.app/v1/vpn-gateways/<id>' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"Rename a VPN gateway#
/v1/vpn-gateways/{id}- Operation
update_vpn_gateway- Credentials
- API token, Portal session
- Requires
- Permission
operate
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Request bodyapplication/json
| Field | Type | Description |
|---|---|---|
namerequired | string |
Responses
200The renamed VPN gateway.application/json
| Field | Type | Description |
|---|---|---|
vpn_gatewayrequired | VpnGateway | |
idrequired | string | |
zonerequired | string | |
namerequired | string | |
planrequired | string | |
staterequired | string | One of creating, running, error, deleting |
moderequired | string | One of wireguard, headscale |
hostnamerequired | string | null | A headscale gateway's DNS name; point it at public_ipv4 and public_ipv6. |
login_serverrequired | string | null | What Tailscale clients log in to (https://<hostname>); null for wireguard. |
network_idsrequired | array of string | |
networksrequired | array of VpnGatewayNetwork | Empty in lists. |
idrequired | string | |
namerequired | string | |
cidrrequired | string | The network's IPv4 subnet, routed to the peers. |
addressrequired | string | null | The gateway's own address on the network, where VPN traffic comes from. Null in lists and until placed. |
tunnel_networkrequired | string | |
tunnel_addressrequired | string | The gateway's own address in the tunnel network. |
listen_portrequired | integer | |
public_ipv4required | string | null | |
public_ipv6required | string | null | |
endpointrequired | string | null | What peers dial: <ipv4>:51820, or [<ipv6>]:51820 without the IPv4 add-on. Null in lists and until placed. |
public_keyrequired | string | null | The gateway's WireGuard public key, generated on its VM. Null in lists and until the gateway reported it. |
peer_countrequired | integer | |
is_healthyrequired | boolean | False in lists. |
health_detailrequired | string | Empty in lists. |
configuration_generationrequired | integer | |
dnsrequired | VpnGatewayDns | null | A 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. |
hostnamerequired | string | |
recordsrequired | array of object | |
typerequired | string | One of A, AAAA |
namerequired | string | |
valuerequired | string | |
is_readyrequired | boolean | The hostname resolves to every record's address. |
instructionsrequired | string | What to do, in one sentence for a person. |
problemrequired | string | null | Why the name is not ready; null when it is. |
active_operationrequired | Operation | null | |
idrequired | string | |
kindrequired | string | One 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_idrequired | string | null | |
storage_idrequired | string | null | |
backup_idrequired | string | null | |
template_idrequired | string | null | |
router_idrequired | string | null | |
floating_ip_idrequired | string | null | |
node_id | string | Set on node maintenance operations (operator only); absent otherwise. |
load_balancer_id | string | null | Set on the operations that create and delete a load balancer. |
database_id | string | null | Set on the operations that create and delete a managed database. |
edge_id | string | null | Set on the operations that sync and delete a network edge. |
vpn_gateway_id | string | null | Set on the operations that sync and delete a VPN gateway. |
snapshot_id | string | null | Set on the operations that create and delete a snapshot, and on a storage.create that clones one. |
kubernetes_cluster_id | string | null | Set on the operations of a managed Kubernetes cluster. |
node_pool_id | string | null | Set on the operations of a Kubernetes node pool. |
kubernetes_host_id | string | Set on a regional host cluster bootstrap (operator only); absent otherwise. |
statusrequired | string | One of pending, running, succeeded, failed, cancelled |
steprequired | string | Machine name of the current step, e.g. create_disk or transfer_cross_zone. |
step_indexrequired | integer | |
step_countrequired | integer | |
errorrequired | string | Empty unless the operation failed. |
created_atrequired | string (date-time) | |
started_atrequired | string (date-time) | null | |
finished_atrequired | string (date-time) | null | |
deadline_atrequired | string (date-time) | |
actor | string | Who asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations. |
progress | MigrationProgress | Present on GET /v1/operations/{id} while a server.migrate drives a live transfer. |
staterequired | string | One of reserved, detached, preparing, sending, switched, aborting |
source_node_idrequired | string | |
target_node_idrequired | string | |
phaserequired | string | How far the nodes report the current attempt.One of , preparing, transferring, completed, failed |
attemptrequired | integer | Which send this is under the convergence policy, from 1. |
iterationrequired | integer | Memory passes so far in the current attempt. |
transferred_bytesrequired | integer | |
total_bytesrequired | integer | 0 when the hypervisor does not report it. |
dirty_bytes_per_secondrequired | integer | |
downtime_millisecondsrequired | integer | The pause the guest took at handover, once completed. |
detailrequired | string | |
reported_atrequired | string (date-time) | null | The reporting node's clock. |
events | array of OperationEvent | Present on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first. |
atrequired | string (date-time) | |
kindrequired | string | For example target_chosen, send_started, handed_over, undoing, cold_fallback, move_cancelled, recovery_started, succeeded, failed. |
messagerequired | string | |
datarequired | object | |
created_atrequired | string (date-time) |
- 400The request is invalid;
detailsays 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_credentialson 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
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#
/v1/vpn-gateways/{id}- Operation
delete_vpn_gateway- Credentials
- API token, Portal session
- Requires
- Permission
operate
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
202Accepted; poll the operation.application/json · OperationEnvelope
| Field | Type | Description |
|---|---|---|
operationrequired | Operation | |
idrequired | string | |
kindrequired | string | One 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_idrequired | string | null | |
storage_idrequired | string | null | |
backup_idrequired | string | null | |
template_idrequired | string | null | |
router_idrequired | string | null | |
floating_ip_idrequired | string | null | |
node_id | string | Set on node maintenance operations (operator only); absent otherwise. |
load_balancer_id | string | null | Set on the operations that create and delete a load balancer. |
database_id | string | null | Set on the operations that create and delete a managed database. |
edge_id | string | null | Set on the operations that sync and delete a network edge. |
vpn_gateway_id | string | null | Set on the operations that sync and delete a VPN gateway. |
snapshot_id | string | null | Set on the operations that create and delete a snapshot, and on a storage.create that clones one. |
kubernetes_cluster_id | string | null | Set on the operations of a managed Kubernetes cluster. |
node_pool_id | string | null | Set on the operations of a Kubernetes node pool. |
kubernetes_host_id | string | Set on a regional host cluster bootstrap (operator only); absent otherwise. |
statusrequired | string | One of pending, running, succeeded, failed, cancelled |
steprequired | string | Machine name of the current step, e.g. create_disk or transfer_cross_zone. |
step_indexrequired | integer | |
step_countrequired | integer | |
errorrequired | string | Empty unless the operation failed. |
created_atrequired | string (date-time) | |
started_atrequired | string (date-time) | null | |
finished_atrequired | string (date-time) | null | |
deadline_atrequired | string (date-time) | |
actor | string | Who asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations. |
progress | MigrationProgress | Present on GET /v1/operations/{id} while a server.migrate drives a live transfer. |
staterequired | string | One of reserved, detached, preparing, sending, switched, aborting |
source_node_idrequired | string | |
target_node_idrequired | string | |
phaserequired | string | How far the nodes report the current attempt.One of , preparing, transferring, completed, failed |
attemptrequired | integer | Which send this is under the convergence policy, from 1. |
iterationrequired | integer | Memory passes so far in the current attempt. |
transferred_bytesrequired | integer | |
total_bytesrequired | integer | 0 when the hypervisor does not report it. |
dirty_bytes_per_secondrequired | integer | |
downtime_millisecondsrequired | integer | The pause the guest took at handover, once completed. |
detailrequired | string | |
reported_atrequired | string (date-time) | null | The reporting node's clock. |
events | array of OperationEvent | Present on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first. |
atrequired | string (date-time) | |
kindrequired | string | For example target_chosen, send_started, handed_over, undoing, cold_fallback, move_cancelled, recovery_started, succeeded, failed. |
messagerequired | string | |
datarequired | object |
- 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_credentialson 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
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#
/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
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Request bodyapplication/json
| Field | Type | Description |
|---|---|---|
shared | boolean | A key of the shared user (servers, CI) instead of one for your own devices. |
reusable | boolean | |
ephemeral | boolean | |
expiration_hours | integer | How long the key may be used to join; joined devices stay. |
Responses
201The key, shown once.application/json
| Field | Type | Description |
|---|---|---|
auth_keyrequired | VpnGatewayAuthKey | |
keyrequired | string | |
expires_atrequired | string (date-time) | |
reusablerequired | boolean | |
ephemeralrequired | boolean | |
userrequired | string | The tailnet user the key's devices belong to: your email, or devices for a shared key. |
login_serverrequired | string | |
installrequired | array of object | One entry per platform, in the order linux, macos, windows, ios, android. |
platformrequired | string | One of linux, macos, windows, ios, android |
titlerequired | string | |
commandrequired | string | null | One command to paste, with the key in it; null on phones. |
stepsrequired | array of string | |
uses_registration_coderequired | boolean | The device signs in without the key and shows a code to register with POST /v1/vpn-gateways/{id}/devices. |
join_commandrequired | string | The Linux command line: sudo tailscale up --login-server=… --authkey=… --accept-routes. |
- 400The request is invalid;
detailsays 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_credentialson 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
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#
/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
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
200The devices.application/json
| Field | Type | Description |
|---|---|---|
itemsrequired | array of VpnGatewayDevice | |
idrequired | string | |
namerequired | string | |
userrequired | string | The tailnet user the device belongs to: a person's email, or devices for shared ones. |
is_minerequired | boolean | The device belongs to the caller. |
addressesrequired | array of string | Tailnet addresses. |
onlinerequired | boolean | |
last_seen_atrequired | string (date-time) | null | |
created_atrequired | string (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_credentialson 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
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#
/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
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Request bodyapplication/json
| Field | Type | Description |
|---|---|---|
registration_keyrequired | string | The code the app shows after signing in. |
Responses
201The registered device.application/json
| Field | Type | Description |
|---|---|---|
devicerequired | VpnGatewayDevice | |
idrequired | string | |
namerequired | string | |
userrequired | string | The tailnet user the device belongs to: a person's email, or devices for shared ones. |
is_minerequired | boolean | The device belongs to the caller. |
addressesrequired | array of string | Tailnet addresses. |
onlinerequired | boolean | |
last_seen_atrequired | string (date-time) | null | |
created_atrequired | string (date-time) | null |
- 400The request is invalid;
detailsays 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_credentialson 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
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#
/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
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string | |
devicerequired | path | string | The 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_credentialson 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
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#
/v1/vpn-gateways/{id}/peers- Operation
list_vpn_gateway_peers- Credentials
- API token, Portal session
- Requires
- Permission
read
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Responses
200Every peer of the gateway, by name.application/json
| Field | Type | Description |
|---|---|---|
itemsrequired | array of VpnGatewayPeer | |
idrequired | string | |
namerequired | string | |
kindrequired | string | One of client, site |
public_keyrequired | string | |
tunnel_addressrequired | string | The peer's address in the gateway's tunnel network. |
remote_networksrequired | array of string | |
endpointrequired | string | null | |
persistent_keepalive_secondsrequired | integer | |
owner_user_idrequired | string | null | The user who added the peer for a device of their own. |
is_minerequired | boolean | The peer is a device of the caller. |
created_atrequired | string (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_credentialson 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
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#
/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
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
Request bodyapplication/json · CreateVpnGatewayPeerRequest
| Field | Type | Description |
|---|---|---|
namerequired | string | |
kind | string | One of client, site |
public_keyrequired | string | The peer's WireGuard public key (44 characters of base64). |
remote_networks | array of string | A site's IPv4 networks (CIDR) behind it; not for a client. |
endpoint | string | Where the gateway can reach the peer, <ipv4>:<port> or [<ipv6>]:<port>; leave it out for a peer that roams. |
persistent_keepalive_seconds | integer | Keepalives the gateway sends the peer, for a site behind NAT that the gateway must reach first. |
mine | boolean | A 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
| Field | Type | Description |
|---|---|---|
peerrequired | VpnGatewayPeer | |
idrequired | string | |
namerequired | string | |
kindrequired | string | One of client, site |
public_keyrequired | string | |
tunnel_addressrequired | string | The peer's address in the gateway's tunnel network. |
remote_networksrequired | array of string | |
endpointrequired | string | null | |
persistent_keepalive_secondsrequired | integer | |
owner_user_idrequired | string | null | The user who added the peer for a device of their own. |
is_minerequired | boolean | The peer is a device of the caller. |
created_atrequired | string (date-time) | |
operationrequired | Operation | |
idrequired | string | |
kindrequired | string | One 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_idrequired | string | null | |
storage_idrequired | string | null | |
backup_idrequired | string | null | |
template_idrequired | string | null | |
router_idrequired | string | null | |
floating_ip_idrequired | string | null | |
node_id | string | Set on node maintenance operations (operator only); absent otherwise. |
load_balancer_id | string | null | Set on the operations that create and delete a load balancer. |
database_id | string | null | Set on the operations that create and delete a managed database. |
edge_id | string | null | Set on the operations that sync and delete a network edge. |
vpn_gateway_id | string | null | Set on the operations that sync and delete a VPN gateway. |
snapshot_id | string | null | Set on the operations that create and delete a snapshot, and on a storage.create that clones one. |
kubernetes_cluster_id | string | null | Set on the operations of a managed Kubernetes cluster. |
node_pool_id | string | null | Set on the operations of a Kubernetes node pool. |
kubernetes_host_id | string | Set on a regional host cluster bootstrap (operator only); absent otherwise. |
statusrequired | string | One of pending, running, succeeded, failed, cancelled |
steprequired | string | Machine name of the current step, e.g. create_disk or transfer_cross_zone. |
step_indexrequired | integer | |
step_countrequired | integer | |
errorrequired | string | Empty unless the operation failed. |
created_atrequired | string (date-time) | |
started_atrequired | string (date-time) | null | |
finished_atrequired | string (date-time) | null | |
deadline_atrequired | string (date-time) | |
actor | string | Who asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations. |
progress | MigrationProgress | Present on GET /v1/operations/{id} while a server.migrate drives a live transfer. |
staterequired | string | One of reserved, detached, preparing, sending, switched, aborting |
source_node_idrequired | string | |
target_node_idrequired | string | |
phaserequired | string | How far the nodes report the current attempt.One of , preparing, transferring, completed, failed |
attemptrequired | integer | Which send this is under the convergence policy, from 1. |
iterationrequired | integer | Memory passes so far in the current attempt. |
transferred_bytesrequired | integer | |
total_bytesrequired | integer | 0 when the hypervisor does not report it. |
dirty_bytes_per_secondrequired | integer | |
downtime_millisecondsrequired | integer | The pause the guest took at handover, once completed. |
detailrequired | string | |
reported_atrequired | string (date-time) | null | The reporting node's clock. |
events | array of OperationEvent | Present on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first. |
atrequired | string (date-time) | |
kindrequired | string | For example target_chosen, send_started, handed_over, undoing, cold_fallback, move_cancelled, recovery_started, succeeded, failed. |
messagerequired | string | |
datarequired | object |
- 400The request is invalid;
detailsays 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_credentialson 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;
detailnames the limit andreasonisquota_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
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#
/v1/vpn-gateways/{id}/peers/{peer}- Operation
delete_vpn_gateway_peer- Credentials
- API token, Portal session
- Requires
- Permission
operate
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string | |
peerrequired | path | string | The peer's id. |
Responses
202Accepted; poll the operation.application/json · OperationEnvelope
| Field | Type | Description |
|---|---|---|
operationrequired | Operation | |
idrequired | string | |
kindrequired | string | One 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_idrequired | string | null | |
storage_idrequired | string | null | |
backup_idrequired | string | null | |
template_idrequired | string | null | |
router_idrequired | string | null | |
floating_ip_idrequired | string | null | |
node_id | string | Set on node maintenance operations (operator only); absent otherwise. |
load_balancer_id | string | null | Set on the operations that create and delete a load balancer. |
database_id | string | null | Set on the operations that create and delete a managed database. |
edge_id | string | null | Set on the operations that sync and delete a network edge. |
vpn_gateway_id | string | null | Set on the operations that sync and delete a VPN gateway. |
snapshot_id | string | null | Set on the operations that create and delete a snapshot, and on a storage.create that clones one. |
kubernetes_cluster_id | string | null | Set on the operations of a managed Kubernetes cluster. |
node_pool_id | string | null | Set on the operations of a Kubernetes node pool. |
kubernetes_host_id | string | Set on a regional host cluster bootstrap (operator only); absent otherwise. |
statusrequired | string | One of pending, running, succeeded, failed, cancelled |
steprequired | string | Machine name of the current step, e.g. create_disk or transfer_cross_zone. |
step_indexrequired | integer | |
step_countrequired | integer | |
errorrequired | string | Empty unless the operation failed. |
created_atrequired | string (date-time) | |
started_atrequired | string (date-time) | null | |
finished_atrequired | string (date-time) | null | |
deadline_atrequired | string (date-time) | |
actor | string | Who asked for the operation: user:<id>, token:<name>, operator, system:<component>; empty on older operations. |
progress | MigrationProgress | Present on GET /v1/operations/{id} while a server.migrate drives a live transfer. |
staterequired | string | One of reserved, detached, preparing, sending, switched, aborting |
source_node_idrequired | string | |
target_node_idrequired | string | |
phaserequired | string | How far the nodes report the current attempt.One of , preparing, transferring, completed, failed |
attemptrequired | integer | Which send this is under the convergence policy, from 1. |
iterationrequired | integer | Memory passes so far in the current attempt. |
transferred_bytesrequired | integer | |
total_bytesrequired | integer | 0 when the hypervisor does not report it. |
dirty_bytes_per_secondrequired | integer | |
downtime_millisecondsrequired | integer | The pause the guest took at handover, once completed. |
detailrequired | string | |
reported_atrequired | string (date-time) | null | The reporting node's clock. |
events | array of OperationEvent | Present on GET /v1/operations/{id}; the newest 100 entries of the operation's log, oldest first. |
atrequired | string (date-time) | |
kindrequired | string | For example target_chosen, send_started, handed_over, undoing, cold_fallback, move_cancelled, recovery_started, succeeded, failed. |
messagerequired | string | |
datarequired | object |
- 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_credentialson 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
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#
/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
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string | |
peerrequired | path | string | The peer's id. |
Responses
200The configuration.application/json
| Field | Type | Description |
|---|---|---|
configurationrequired | string | |
filenamerequired | string | A file name for it, e.g. office.conf: wg-quick names the interface after it. |
private_key_placeholderrequired | string |
- 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_credentialson 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
curl 'https://cloud.ankra.app/v1/vpn-gateways/<id>/peers/<peer>/configuration' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"