License Integration for JVM Plugins
Two integration paths, one contract. Bundle UlisesLib and call the library from your jar, or call the public validation endpoint from your own code. Both return the same license data and enforce the same rules.
- Path A
- UlisesLib.jar
- Path B
- REST endpoint
- Ecosystem
- PaperMC, Spigot, JVM
- Protocol
- REST over TLS 1.3
Choosing your integration
There are two supported ways to license a plugin, and neither one is the fallback for the other. Pick the one that matches how you ship, or mix them across products.
UlisesLib is a Java library you shade into your plugin jar. It owns the HTTP client, the retry policy, the HWID collector and the auto-updater, so your code is a handful of method calls and everything else stays off your plate.
- JVM plugins that ship one jar and want licensing to be a three line change
- Products that also use the built-in update and checksum helpers
- Teams that would rather not write HTTP, retry and backoff code themselves
- Products that are not JVM, or that ship native code as the real payload
- Plugins you want to obfuscate aggressively, since the library is a visible third party jar
- Anything that needs the response as a signed, offline-checkable token
The validation endpoint is a single public HTTPS POST. You call it from your own code, you decide how that code is packaged, obfuscated or compiled to native, and the response carries a signed ES256 token you can verify without trusting anything else on the box.
- Plugins where you want the license check buried in your own obfuscated or native code
- Non JVM runtimes and external tools that talk to Ulises Licenses over HTTP
- Setup that wants to keep the SDK jar out of the download entirely
- Plugins that want the free built-in updater and checksum verification
- Setups that do not want to own retries, timeouts and rate limit handling
- Anyone looking for a way to skip verifying the response
UlisesLib Core Runtime Binary (UlisesLib.jar)
Compiled binaries are distributed directly through authenticated developer dashboard accounts to bind telemetry, watermarks, and security tokens to your registered products.
Documentation Directory
Add UlisesLib.jar to your Gradle or Maven build and bundle it into your plugin jar. Covers dependencies, shading, version pinning, and verifying setup.
Load your license configuration and validate it on plugin startup, step by step. Includes async verification, error codes, periodic re-checks, and safe logic.
A complete PaperMC plugin class with license validation, retries, and periodic checks end to end. Copy the lifecycle pattern with config and thread safety.
Every UlisesLib method reference: license info, status, subtype, and error handling. Includes signatures, return values, and error codes for Java and Kotlin.
How UlisesLib handles backend outages and how your plugin should respond. Covers timeouts, bounded retries, transient error codes, and offline behavior.
Check for, download, and verify product updates directly through UlisesLib. Includes checksums, watermarked builds, atomic replacement, and version comparison.
What to do and avoid when integrating license validation into plugins. Covers async calls, error codes, HWID flows, update safety, and console hygiene.
Validate licenses with a plain HTTP POST from your own plugin code. Covers when to pick the endpoint over the SDK, the request flow, rate limits, and the signed token.
Full reference for POST /api/endpoint/validate/license. Every request field, the 200 response tree, every error status and flag, plus per-key rate limits.
The ES256 public key for endpoint response tokens: current kid, JWKS URL, JWK and SPKI formats, and rotation rules.
Verify the ES256 signature on the response token in Java, Node.js, and Python. Pin the key by kid, check alg, aud, exp, and the hwid claim.
How to ship an endpoint-based license check safely: retries with backoff, nonce handling, keeping keys out of the jar, obfuscation notes, and logging hygiene.
Developer questions
Which integration path should I use?
Either one. Bundle UlisesLib if you want a library to call, or call the public validation endpoint from your own code if you want no dependency in your jar. Both enforce the same rules and return the same data.
How do I add licensing to my plugin?
With the SDK: download UlisesLib.jar, shade it into your build, verify the buyer's key asynchronously on startup, and re-check every 10 minutes. With the endpoint: POST your apiKey, productId, licenseKey and hwid to /api/endpoint/validate/license, then verify the returned token.
How do I tell a network hiccup from a rejected license?
With the SDK, use getLastErrorCode(). With the endpoint, only 400, 401, 403, 404 and 409 are definitive; 429 and 5xx are transient and should be retried with backoff.
Does it work outside Minecraft plugins?
Yes. UlisesLib is plain JVM bytecode, so Java, Kotlin, BungeeCord proxies, and standalone desktop or server software all work. The endpoint is plain HTTPS and works from any runtime with an HTTP client.
Related guides
Built by Ulises - Citymoon Dynamics