API: Managing Servers and Users

This article shows how to list your servers, manage WireGuard users and check device status with the WireGuard REST API. You'll need an API key first: see WireGuard REST API: Getting Started.

Every example sends the Authorization and Accept: application/json headers. Replace wg_YOUR_KEY with your key and the IDs with your own.

List your servers

GET /api/wg/servers

Returns the active dedicated servers on your account.

curl -s \
  -H "Authorization: Bearer wg_YOUR_KEY" \
  -H "Accept: application/json" \
  https://portal.premiervpn.net/api/wg/servers

Response:

{
  "servers": [
    {
      "id": 1,
      "assignment_id": 5,
      "name": "WG-NL-123",
      "ip_address": "203.0.113.10",
      "location": "Netherlands",
      "wg_port": 51820,
      "wg_subnet": "10.66.66.0/24",
      "status": "active"
    }
  ]
}

Use assignment_id, not id, wherever an endpoint asks for {assignment_id}.

status is active, maintenance or offline.

List users on a server

GET /api/wg/servers/{assignment_id}/users

Returns your WireGuard users on that server, with live status and data usage.

curl -s \
  -H "Authorization: Bearer wg_YOUR_KEY" \
  -H "Accept: application/json" \
  https://portal.premiervpn.net/api/wg/servers/5/users

Response:

{
  "server": "WG-NL-123",
  "users": [
    {
      "id": 12,
      "client_name": "laptop",
      "client_ip": "10.66.66.2",
      "client_public_key": "...",
      "server_public_key": "...",
      "endpoint": "203.0.113.10:51820",
      "dns": "1.1.1.1, 8.8.8.8",
      "status": "active",
      "online": true,
      "last_seen": "1 minute ago",
      "last_handshake": 1791100000,
      "rx_bytes": 1048576,
      "tx_bytes": 524288,
      "rx_formatted": "1 MB",
      "tx_formatted": "512 KB",
      "created_at": "2026-10-01T10:00:00+00:00"
    }
  ]
}

last_handshake is a Unix timestamp (0 if the device has never connected). rx_bytes and tx_bytes are counted by the server since the tunnel interface last started: rx is data received from the device, tx is data sent to it.

Create a user

POST /api/wg/servers/{assignment_id}/users

Creates a WireGuard user and returns its config file and keys.

curl -s -X POST \
  -H "Authorization: Bearer wg_YOUR_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"client_name": "my-phone"}' \
  https://portal.premiervpn.net/api/wg/servers/5/users

client_name is required. Use letters, numbers, hyphens and underscores only, up to 50 characters. Each name can only be used once per server. A name that's taken returns 409 with the code name_unavailable.

Response (201):

{
  "message": "User 'my-phone' created.",
  "user": {
    "id": 13,
    "client_name": "my-phone",
    "client_ip": "10.66.66.3",
    "client_public_key": "...",
    "server_public_key": "...",
    "endpoint": "203.0.113.10:51820",
    "dns": null
  },
  "config": "[Interface]\nPrivateKey = ...\n...",
  "keys": {
    "client_private_key": "...",
    "client_public_key": "...",
    "preshared_key": "...",
    "server_public_key": "..."
  }
}

• config: the complete .conf file. Save it to a file and import it into WireGuard.
• keys: the individual keys, if you build configs yourself.

In this response, dns can be null and the DNS line in config empty. Before saving the config, fetch the user with GET /api/wg/users/{user_id}, which returns the stored config with its DNS servers (1.1.1.1, 8.8.8.8 by default).

Get a single user

GET /api/wg/users/{user_id}

Returns the user's details, live status, full config file and keys. {user_id} is the id from the users list.

curl -s \
  -H "Authorization: Bearer wg_YOUR_KEY" \
  -H "Accept: application/json" \
  https://portal.premiervpn.net/api/wg/users/12

The response has a user object (the same status fields as the users list), plus config and keys.

Remove a user

DELETE /api/wg/users/{user_id}

Removes the user from the server straight away, along with all of its port forwards. Its config stops working. This can't be undone.

curl -s -X DELETE \
  -H "Authorization: Bearer wg_YOUR_KEY" \
  -H "Accept: application/json" \
  https://portal.premiervpn.net/api/wg/users/12

Response:

{
  "message": "User 'laptop' removed from WG-NL-123."
}

If you set a bandwidth limit on this user, remove it first with DELETE /api/wg/users/{user_id}/bandwidth. Otherwise the limit can stay on the server and apply to the next user given the same internal IP.

Check device status

GET /api/wg/servers/{assignment_id}/status

Returns live status for all your users on the server.

curl -s \
  -H "Authorization: Bearer wg_YOUR_KEY" \
  -H "Accept: application/json" \
  https://portal.premiervpn.net/api/wg/servers/5/status

Response:

{
  "server": "WG-NL-123",
  "checked_at": "2026-10-04T09:30:00+00:00",
  "devices": [
    {
      "id": 12,
      "client_name": "laptop",
      "client_ip": "10.66.66.2",
      "online": true,
      "last_seen": "1 minute ago",
      "last_handshake": 1791100000,
      "rx_bytes": 1048576,
      "tx_bytes": 524288,
      "rx_formatted": "1 MB",
      "tx_formatted": "512 KB"
    }
  ]
}

A device is online if its last handshake was within the past 3 minutes.

Bandwidth limits and DNS-over-TLS

You can also set per-user speed limits and choose your server's DNS-over-TLS resolvers. Both are covered in the Complete Endpoint Reference.