Protect every build.
Control every key.

01

OVERVIEW

What developers need

The developer does not need your Cloudflare account, database ID, admin password, or dashboard access. Give them only the endpoint and the exact product code created in the Products page.

✦

Example product code

VOYAGE must exactly match the code in this dashboard.

✓

Persistent installation IDGenerate once and save it in the plugin folder.

✓

Asynchronous requestNever block the Minecraft main thread.

✓

Fail safelyDisable only the plugin when definitely invalid.

✓

Verify the full responseCheck product and installation ID, not only valid=true.

02

HTTP REQUEST

POST validation payload

Send JSON over HTTPS with a five-second connection and read timeout.

JSON request

{
  "licenseKey": "VOYAGE-ABCDE-FGHIJ-KLMNO",
  "product": "VOYAGE",
  "installationId": "a-persistent-generated-uuid",
  "serverAddress": "play.example.com:25565",
  "pluginVersion": "1.0.0"
}

Required: licenseKey, product, and installationId. The server address and plugin version are useful metadata.

03

API RESPONSE

Accepted and rejected results

Valid response

{
  "valid": true,
  "reason": "VALID",
  "product": "VOYAGE",
  "installationId": "a-persistent-generated-uuid",
  "issuedAt": 1783785600000,
  "revalidateAfter": 1783807200000,
  "graceUntil": 1783958400000
}

Invalid response

{
  "valid": false,
  "reason": "INSTALLATION_LIMIT_REACHED",
  "product": "VOYAGE",
  "installationId": "a-persistent-generated-uuid"
}

INVALID_LICENSESUSPENDEDREVOKEDEXPIREDINSTALLATION_LIMIT_REACHEDMISSING_FIELDS

04

MAVEN

Add Gson and shade it

Gson converts Java request objects to JSON and parses the API response. Relocate it to avoid conflicts with server libraries.

pom.xml

<dependency>
  <groupId>com.google.code.gson</groupId>
  <artifactId>gson</artifactId>
  <version>2.11.0</version>
</dependency>

<relocation>
  <pattern>com.google.gson</pattern>
  <shadedPattern>your.package.libs.gson</shadedPattern>
</relocation>

05

JAVA 8 CLIENT

Minimal validation client

This example uses HttpURLConnection, works on Java 8, reads error bodies, and always disconnects.

LicenseClient.java

public final class LicenseClient {
    private static final String ENDPOINT =
        "https://licenses.vaeloriamc.net/api/v1/licenses/validate";

    private final Gson gson = new Gson();

    public LicenseResponse validate(LicenseRequest request) throws IOException {
        HttpURLConnection connection = null;
        try {
            connection = (HttpURLConnection) new URL(ENDPOINT).openConnection();
            connection.setRequestMethod("POST");
            connection.setConnectTimeout(5000);
            connection.setReadTimeout(5000);
            connection.setDoOutput(true);
            connection.setUseCaches(false);
            connection.setRequestProperty("Content-Type", "application/json; charset=UTF-8");
            connection.setRequestProperty("Accept", "application/json");
            connection.setRequestProperty("User-Agent", "Plugin-License-Client/1.0");

            byte[] body = gson.toJson(request).getBytes(StandardCharsets.UTF_8);
            connection.setFixedLengthStreamingMode(body.length);
            try (OutputStream output = connection.getOutputStream()) {
                output.write(body);
            }

            int status = connection.getResponseCode();
            InputStream stream = status >= 200 && status < 300
                ? connection.getInputStream()
                : connection.getErrorStream();
            if (stream == null) throw new IOException("Empty API response");

            StringBuilder json = new StringBuilder();
            try (BufferedReader reader = new BufferedReader(
                    new InputStreamReader(stream, StandardCharsets.UTF_8))) {
                String line;
                while ((line = reader.readLine()) != null) json.append(line);
            }
            if (json.length() == 0) throw new IOException("Empty API response");
            return gson.fromJson(json.toString(), LicenseResponse.class);
        } finally {
            if (connection != null) connection.disconnect();
        }
    }
}

06

BUKKIT STARTUP

Validate before enabling features

Main plugin class

@Override
public void onEnable() {
    saveDefaultConfig();
    getServer().getScheduler().runTaskAsynchronously(this, () -> {
        try {
            LicenseResponse response = licenseClient.validate(buildRequest());
            boolean accepted = response != null
                && response.isValid()
                && "VALID".equalsIgnoreCase(response.getReason())
                && PRODUCT_CODE.equalsIgnoreCase(response.getProduct())
                && installationId.equals(response.getInstallationId());

            getServer().getScheduler().runTask(this, () -> {
                if (!accepted) {
                    getLogger().severe("License validation failed: " + response.getReason());
                    getServer().getPluginManager().disablePlugin(this);
                    return;
                }
                startPluginFeatures();
            });
        } catch (IOException failure) {
            getServer().getScheduler().runTask(this, () -> {
                getLogger().severe("Could not reach the license service.");
                getServer().getPluginManager().disablePlugin(this);
            });
        }
    });
}

!

Do not register important listeners or tasks first

Move normal startup into a method such as startPluginFeatures() and call it only after validation succeeds.

07

SECURITY

Rules developers must follow

01

Never include admin credentialsThe plugin receives only the public endpoint and product code.

02

Never disable TLS checksDo not trust all certificates or bypass hostname verification.

03

Never delete customer dataAn invalid license should only disable the licensed plugin safely.

04

Do not collect private server dataNo player IP lists, files, tokens, passwords, or hardware fingerprints.

05

Remember the current limitationUnsigned JSON can still be patched by a determined attacker. Signed responses are the next upgrade.

License command center

Your software, under control.

Needs attention

Product activity

License directory

No licenses found

One license namespace per plugin.

Products

Integrate Crown licensing into any Minecraft plugin.

What developers need

POST validation payload

Accepted and rejected results

Add Gson and shade it

Minimal validation client

Validate before enabling features

Rules developers must follow

Protect a compiled Minecraft plugin.

Upload plugin

Are you sure?

Protect every build.Control every key.

Enter the command center

Your software, under control.

Needs attention

Product activity

License directory

No licenses found

One license namespace per plugin.

Products

Integrate Crown licensing into any Minecraft plugin.

What developers need

POST validation payload

Accepted and rejected results

Add Gson and shade it

Minimal validation client

Validate before enabling features

Rules developers must follow

Protect a compiled Minecraft plugin.

Upload plugin

Protect every build.
Control every key.