WP Guardian API¶

Introduction¶

This topic is aimed at Plesk or cPanel partners who want to sell VPSs with WP Guardian installed and licensed. We provide a step-by-step procedure and example API calls required for installing and licensing WP Guardian on a client's VPS.

Prerequisites¶

As a Plesk or cPanel partner, you need to have access to their corresponding APIs: Key Administrator for Plesk and Manage2 for cPanel, respectively.

Having access means that you have credentials necessary to use the APIs, which are basic $AUTH_TOKEN for Key Administrator and the login/password pair for Manage2.

Note

If you do not have the credentials mentioned above, contact your Plesk or cPanel account manager.

The Overall Algorithm and Detailed Schemes¶

The procedure starts with a client placing an order (step 1) and ends with you giving a ready-to-use VPS to the client (step 6). In between, you must take the following steps:

(2) Create a WP Guardian user.

(3) Create a WP Guardian license.

(4) Get the connection string snippet.

(5) Run the connection string snippet on the client's VPS.

Except for step 3, all of the steps above are similar between Key Administrator and Manage2. Therefore we will have two separate sections describing how to create a WP Guardian license with Key Administrator and Manage2.

To help you understand the differences between Key Administrator and Manage2 better, we attach the detailed scheme for each of these APIs. From there onwards, we also use the numeration shown on those schemes (for example, API Request 2.1 or Response 4.2). Should you find yourself lost in the text, refer to the schemes below for clarification.

2. Creating a WP Guardian User¶

To create a user via the WP Guardian API, you first need to get a management token. To do so, contact a WP Guardian sales representative or the Plesk Customer Success Team.

Once you get the management token, send the request of the following pattern adding the token to the Authorization header:

Request 2.1¶

POST https://app.wpguardian.io/api/v1/security-dashboard/management/users HTTP/1.1
Authorization: Bearer $MANAGEMENT_TOKEN
Content-Type: application/json
{
  "email": "john.doe@example.com",
  "firstName": "John",
  "lastName": "Doe"
}

If Request 2.1 is successful, you will get the response of the following pattern:

Response 2.3¶

HTTP/1.1 201 Created
{
  "data": {
    "userGuid": "1092a1a6-a716-400d-aba5-ad853a330561",
    "teamGuid": "1247c8bc-6d5d-41f6-9bda-007a6e6fb20c",
    "userToken": "368ded8f-883a-4759-9f28-8906c3e5136c"
  }
}

The response contains three values. Save two of them (teamGuid and userToken) to use later:

teamGuid is used to upgrade or terminate a WP Guardian license.
userToken helps to connect more servers to the user's account.

If Request 2.1 is incorrect, you will get the following error response:

Error response: Invalid token response¶

HTTP/1.1 401 Unauthorized

If the user with the submitted information already exists, you will get the following error response:

Error response: The user already exists response¶

HTTP/1.1 409 Conflict

3. Creating a WP Guardian License (Key Administrator)¶

Note

Each WP Guardian user can only have one active license at a time.

You create a license for a WP Guardian user via the Key Administrator Partner API.

To create a license, send the request of the following pattern:

Request 3.1¶

POST https://api.central.plesk.com/30/keys?return-key-state=yes
Authorization: Basic: $AUTH_TOKEN
Content-Type: application/json
{
    "activationInfo": { "uid": "1247c8bc-6d5d-41f6-9bda-007a6e6fb20c" },
    "items": [
        {
            "item": "WPG-PLSK-1-1M"
        }
    ]
}

where

$AUTH_TOKEN is a token necessary to access the Key Administrator Partner API. Each Plesk partner has it.
uid in activationInfo is teamGuid from Response 2.3.
item in items is the license type and can be one of the following:
- WPG-PLSK-1-1M
- WPG-PLSK-5-1M
- WPG-PLSK-10-1M
- WPG-PLSK-30-1M
- WPG-PLSK-50-1M
Note

To see the list of all available WP Guardian license types, refer to the "Partner API 3.0 Constants" section ("category":"WP Guardian Keys").

If Request 3.1 is successful, you will get the response of the following pattern:

Response 3.4¶

HTTP/1.1 201 Created
{
  "ownerId": "700540512",
  "keyIdentifiers": {
    "keyId": 17654729,
    "keyNumber": "WPG.17654729.0000",
    "activationCode": "AB1234-CD5678-EF9012-GH123-IJ456",
    "activationLink": "https://app.wpguardian.io/licensing/activate-license?code=AB1234-CD5678-EF9012-GH123-IJ456&product=WP+Guardian+1+Site"
  },
  "parentKeyIdentifiers": null,
  "activationInfo": {
    "uid": "1247c8bc-6d5d-41f6-9bda-007a6e6fb20c",
    "activated": true
  },
  "ipAddressBinding": null,
  "nickname": "",
  "productConfigurationId": null,
  "items": [
    {
      "externalId": null,
      "item": "WPG-PLSK-1-1M"
    }
  ],
  "creationDate": "2024-09-12T10:34:11.741Z",
  "lastModificationDate": "2024-09-12T10:34:11.763Z",
  "updateDate": "2024-10-12T00:00:00.000Z",
  "expirationDate": "2024-10-22T00:00:00.000Z",
  "susExpirationDate": null,
  "susStatus": null,
  "supportExpirationDate": null,
  "supportStatus": null,
  "status": "ACTIVE",
  "terminated": false,
  "suspended": false,
  "ownerSuspended": false,
  "autoRenew": true,
  "restrictIPBinding": false,
  "frauds": [],
  "lastReportingDate": null,
  "lastReportingIp": null,
  "lastReportingOs": null,
  "childKeyIdentifiers": [],
  "overridingKeyIdentifiers": null
}

If Request 3.1 is incorrect, you will get the following error response:

Error response: Invalid token response¶

HTTP/1.1 401
Content-Type: application/json
Content-Length: 77
{"code":"401","type":"6011","message":"The request requires authentication."}

If the user already has an active license, you will get the following error response:

Error response: Third party error¶

HTTP/1.1 404 
Content-Type: application/json
{"code":"404","type":"6101","message":"Third party server returned an error"}

3. Creating a WP Guardian License (Manage2)¶

Unlike Key Administrator, Manage2 does not support creating a license already bound to a specific user. You first create a non-active license, generate the activation link for the license, and then send the link to the client. Once the client opens the link, the license becomes active and bound to the client.

Let's see how to go through each step.

Step 1. Create a non-active WP Guardian license by sending the API request of the following pattern:

Request 3.1¶

GET https://manage2.cpanel.net/XMLlicenseAdd.cgi?output=json&packageid=P999994429&sites==500
Authorization Basic: login:password

where

login:password is the login/password pair necessary to access the Manage2 API. Each cPanel partner has it.
packageID is the license type and can be one of the following:
"P999994429": "WP Guardian 500 Sites"
"P999994433": "WP Guardian 1000 Sites"
"P999994441": "WP Guardian 10000+ Sites Pay As You Go"
the sites parameter must match the license type. For example, if the license type is P999994429, then the sites parameter is 500, and so on.

Note

To see the list of all available WP Guardian license types, use the Manage2 API.

Note

The output of the Manage2 API contains two products: "WP Guardian N Sites" and "WP Guardian (cPanel Addon) N Sites Pack". You need the former.

If Request 3.1 is successful, you will get the response of the following pattern:

Response 3.2¶

{
    "monthly_price": "21.34",
    "status": 1,
    "yearly": 0,
    "reason": "Activated EXAMPLECOMPANY license on in the 'example' group.",
    "price": "0.00",
    "promoinfo": "",
    "licenseid": "17654729"
}

From the response, you need to copy the licenseid value to use it later.

Step 2. Generate the activation link by sending the API request of the following pattern:

Request 3.3¶

{
GET https://manage2.cpanel.net/XMLlicenseInfo.cgi?output=json&liscid=17654729
Authorization Basic: login:password
}

where liscid is licenseid from Response 3.2.

If Request 3.3 is successful, you will get the response of the following pattern:

Response 3.4¶

{
    "licenses": {
        "17654729": {
            "accounts": 1,
...
            "activation_link": "https://app.wpguardian.io/licensing/activate-license?code=A00300-GEX111-577J59-A6AG72-AEKX66&product=WP+Guardian+500+Sites ",
...
        }
    },
    "reason": "OK",
    "status": 1,
    "version": 0.7
}

Step 3. Save the activation link received in Response 3.4, and then send it to the client. Make sure that the client opens the link. Opening the link activates the license and binds it to the client.

4. Getting the Connection String Snippet¶

The connection string snippet is a script you need to get from the WP Guardian API. By running the snippet on a client's server, you connect it to WP Guardian.

To get the snippet, send the API request of the following pattern:

Request 4.1¶

GET https://app.wpguardian.io/api/v1/security-dashboard/connection-snippet
Authorization: Bearer $USER_TOKEN
Content-Type: application/json

where $USER_TOKEN is userToken from Response 2.3.

If the API request was correct, you will get the response of the following pattern:

Response 4.2¶

{
    "data": {
        "expireAt": "2024-09-24T17:18:51.697Z",
        "snippet": "<script to run on a client's VPS>"
    }
}

5. Running the Snippet on a Client's VPS¶

The last step is to run the connection string snippet received during the previous step on the client's VPS. Once you have done so, the VPS with WP Guardian is all ready. Congratulations!

Note

The snippet automatically connects a client's VPS to WP Guardian. If, for any reason, the snippet fails, you can resolve the issue by connecting a VPS to WP Guardian manually.