Static keys

What are static license keys?

A static key is a license key that you upload to WunderUpdates. The key is then used to validate the user's right to download the plugin. A static license key can optionally have an expiry date, after which it will no longer be valid. This is a simple way to manage licenses for your plugins if you don't want to use a third-party service.

Keys can be uploaded in bulk by providing a CSV or JSON file with a list of valid keys. This is useful if you have pre-generated a list of keys that you hand out to your customers.

Keys can also be uploaded one by one using the API, this is useful if you are generating license keys on the fly when a new purchase is made it's not complicated to add a single REST API call to WunderUpdates to add the key there.

Limitations of static keys

Static keys are a simple way to manage licenses, but they have some limitations:

No tracking of active installations

WunderUpdates don't keep track of how many active installations (WordPress sites) that is using a specific key. This means that once you have added a key, we can't restrict the number of WordPress sites the key is used on.

Performance impact

There's no strict limit to how many active keys you can have at the same time, but API response times will be affected if you have a large number of keys. The limit is when our internal JSON representation of all your active keys reaches a size of more than 200 kB of data. When the license data is larger than that, the cache mechanism will work differently and response times will be affected.

This can be mitigated by using shorter key strings and by removing keys that are no longer needed.

Configuring your plugin to use static keys

You can configure your plugin to use static keys when you first created it but you can also change the license provider later.

To create a plugin that uses static keys:

curl -X POST https://api.wunderupdates.com/v1/plugins \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"slug": "hello-world", "license": {"type": "static-keys"}}'

Or to update an existing plugin to use static keys:

curl -X POST https://api.wunderupdates.com/v1/plugins/hello-world/license \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"type": "static-keys"}'

To verify that the license provider is set to static keys:

curl -X GET https://api.wunderupdates.com/v1/plugins/hello-world \
  -H "x-api-key: YOUR_API_KEY"

The response should look something like:

{
  "plugin": {
    "latestRelease": "1.0",
    "license": {
      "type": "static-keys"
    },
    "latestPreRelease": "",
    "instanceId": "7282b021-9af6-43bd-bd0b-4de30ebba4b0",
    "versions": [
      {
        "file": "hello-world-1.0.zip",
        "version": "1.0"
      }
    ],
    "slug": "hello-world",
    "latest": "1.0"
  },
  "status": 200
}

Managing keys individually

Managing individual keys with PUT, GET and DELETE

By sending a PUT request to the /v1/plugins/{slug}/license/keys endpoint you can add one or more keys to the plugin.

curl -X PUT https://api.wunderupdates.com/v1/plugins/hello-world/license/keys \
  -H "x-api-key: YOUR_API_KEY" \
  -d '[{ "key": "abc-123-expired", "expires": "2021-01-01"},{ "key": "abc-123-good", "expires": "2099-01-01"}]'

A more practical way is to save the keys in a JSON file and then use the curl @ syntax to read the file content:

curl -X PUT https://api.wunderupdates.com/v1/plugins/hello-world/license/keys \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d @path/to/keys.json

To verify that the new keys are added we use HTTP GET:

curl -X GET https://api.wunderupdates.com/v1/plugins/hello-world/license/keys \
  -H "x-api-key: YOUR_API_KEY"

Will respond with:

{
  "licenses": [
    {
      "key": "abc-123-no-expiry"
    },
    {
      "expires": "2021-01-01",
      "key": "abc-123-expired"
    },
    {
      "expires": "2099-01-01",
      "key": "abc-123-good"
    }
  ],
  "status": 200
}

To remove a key, use HTTP DELETE:

curl -X GET https://api.wunderupdates.com/v1/plugins/hello-world/license/keys/abc-123-no-expiry \
  -H "x-api-key: YOUR_API_KEY"

JSON format

The following fields are supported in the JSON format:

Field	Description
key	Mandatory. The license key
expires	Optional. Expiry date in ISO-8601 format (yyyy-mm-dd)
email	Optional. Email address associated with the license

Managing keys in bulk

In some cases, it may be more practical to overwrite all existing keys with a new set of keys. This can be done by sending a POST request that will overwrite all existing keys with a new set.

Using JSON

In JSON format, assuming that path/to/keys.json is a valid JSON file:

curl -X POST https://api.wunderupdates.com/v1/plugins/hello-world/license/keys \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d @path/to/keys.json

The JSON format when sending a bulk request is the same as when sending individual keys.

Using flat files

Optionally, you can also use a CSV (and friends) file to upload a flat file with keys:

curl -X POST https://api.wunderupdates.com/v1/plugins/hello-world/license/keys \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-separator: comma" \
  -H "x-header-row: yes" \
  -H "Content-Type: text/plain" \
  -d @path/to/keys.csv

The x-separator header is optional and can be set to comma, semicolon or tab depending on the separator used in your file. The default value is the comma.

The x-header-row header is optional and can be set to yes or no depending on if the first row in the file is a header row containing the field names and is skipped. The default is no. Note that if the header row is present and you have set x-header-row: yes, WunderUpdates will simply ignore it. But if you set the header to no, you will end up with a license key that has your column name as the key. You probably don't that.

Bulk file format

The bulk file format is a flat file with one key per line. Each line may contain up to 3 fields: key, expiry date and email.

Each row in the file is interpreted as follows:

1. If the row contains one field, it's interpreted as a key.
2. If the row contains two fields, it's interpreted as a key and expires.
3. If the row contains three fields, it's interpreted as a key, expires and email.

If you need to upload license keys with key and email only, you need to use the JSON format instead.

Check the license key storage size

As mentioned above, the static key license provider has a limit on how large the key storage can be. An easy way to check the current size of the key storage is to request the license data for the plugin and pipe it to wc -c:

curl -s -X GET https://api.wunderupdates.com/v1/plugins/hello-world/license/keys \
  -H "x-api-key: YOUR_API_KEY" | wc -c

Which will return the number of characters in the response:

157

For this example, we had 3 active keys in the plugin, each about 20 characters long, 2 out of the three keys had an expiry date. That works out to about 50 bytes per key which is a good rule of thumb to use. Having 200k bytes available means that you can have about 4000 keys with expiry dates before you reach the limit where performance may be affected.

Note

We are actively working on improving the capacity of the license key storage so that you can have unlimited keys without affecting performance. Watch this space.

Keep an eye on this number as it grows above 200.000. Consider removing keys that are no longer needed.