WireGuard REST API: Getting Started

The WireGuard REST API lets you manage your dedicated WireGuard® servers from your own scripts, panel or billing system. This article covers API keys, authentication, rate limits and response formats.

What you can do

Servers: list the dedicated servers on your account.
Users: create, list, view and remove WireGuard users, and get their config files and keys.
Device status: see which devices are online and how much data each has used.
Port forwarding: list, add and remove port forwards for each user.
Bandwidth limits: set or remove per-user download and upload limits.
DNS-over-TLS: set the encrypted DNS resolvers your server uses.

The API is available to every customer with a dedicated WireGuard server.

Base URL

https://portal.premiervpn.net/api/wg

Create an API key

Sign in at portal.premiervpn.net.
In the sidebar, click WireGuard, then Manage Server.
In the REST API box, click API Keys & Documentation. You can also go straight to /wireguard/api-keys.
Under Create API Key, enter a name such as "Production" and click Generate Key.
Copy the key straight away and store it somewhere safe. It's only shown once.

Keys start with wg_. You can have up to 5 active keys. Each key works for all the dedicated servers on your account.

Manage your keys

The Your API Keys table shows each key's name, the first few characters, when and from which IP it was last used, and whether it's Active or Revoked.

To stop a key working, click Revoke and confirm. Anything using that key stops working immediately. Revoked keys can't be turned back on, so create a new key if you need one.

Authentication

Send your key as a Bearer token in the Authorization header on every request. Also send Accept: application/json, so errors always come back as JSON.

Authorization: Bearer wg_your_api_key_here
Accept: application/json

Example:

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

Send request bodies as JSON with Content-Type: application/json.

Rate limits

Each key can make up to 60 requests per minute. Over that, you get HTTP 429 with the code rate_limited. Wait a minute before trying again.

Calls that change the server, such as creating users or port forwards, connect to your server and can take a few seconds. Wait for each response before sending the next change.

Responses and errors

Responses are JSON. Successful requests return the data directly, with 200, or 201 when something is created.

Most errors include a message and a code:

{
  "error": "Invalid API key.",
  "code": "invalid_api_key"
}

Invalid input (for example a missing field) returns 422 with a message and an errors object listing each problem field. The full list of status and error codes is in the Complete Endpoint Reference.

Security

We store only a SHA-256 hash of each key, never the key itself, so we can't show it to you again.
A key can only reach the servers, users and port forwards on your own account.
Changes made through the API, such as creating or removing users and port forwards, are logged.
Check Last Used regularly. If a key may have leaked, revoke it and create a new one.
The API returns private keys and config files. Keep API responses as safe as the key itself.

Next steps

API: Managing Servers and Users
API: Port Forwarding
API: Complete Endpoint Reference, including bandwidth limits and DNS-over-TLS

Something out of date or unclear? Let us know.