Using the Validation Endpoint
The validation endpoint is a public HTTPS endpoint that answers one question: is this license key valid for this product, on this machine, right now? You call it from your own code. Nothing from Ulises Licenses ships inside your jar, so the check lives entirely in code you wrote and control.
What the endpoint is
One POST, one JSON body, one JSON response. The request carries your product API key, the product id, the buyer's license key and the hardware id of the machine running the plugin. The response carries the full license record plus a signed token that proves the response came from us. The endpoint enforces exactly the same rules the SDK does: license status, expiry, HWID binding, HWID limits and IP limits.
When to choose the endpoint
- You want the license check inside code you package yourself, including native or heavily obfuscated builds
- You do not want a third party jar in your download, or you ship something that is not a JVM plugin
- You want a signed token you can verify offline, so a forged or replayed response is detectable
- You already have a working HTTP client and retry policy in your product
- You want licensing to be a handful of method calls instead of an HTTP layer you maintain
- You want the built-in updater, checksum verification and HWID collection
- You are targeting the widest possible range of server versions and Java runtimes with the least work
- You would rather not think about nonces, rate limits or signature verification
SDK or endpoint
Neither path is a fallback for the other. They are two supported ways to reach the same license data with the same enforcement, and plenty of products end up using both.
| Aspect | UlisesLib SDK | Validation endpoint |
|---|---|---|
| What you add to your build | UlisesLib.jar, shaded into your plugin jar | Nothing. You ship the HTTP client you already have. |
| Where the check lives | Inside the bundled library | Inside your own code, wherever you choose to put it |
| Obfuscation | The library is a known third party artifact and is visible to anyone unzipping your jar | Fully yours to obfuscate, relocate or compile to native |
| Retries and backoff | Built in, up to 5 attempts, exposed through getLastErrorCode() | Yours to write, against documented status codes and Retry-After |
| HWID collection | Collected for you by the library | You compute it and send it as the hwid field |
| Proof of origin | Handled inside the library | ES256 JWS you verify with a pinned public key |
| Auto updates | checkForUpdate, downloadUpdate and verifyChecksum | Not provided. updateInfo tells you a version exists, nothing more. |
| Result data | llIIllll.I result with a typed data tree | The same data tree as JSON, with identical field names |
Request flow
The whole contract is one POST with a JSON body. The license key never goes in the query string.
curl -i -X POST https://www.uliseslicenses.xyz/api/endpoint/validate/license \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "apiKey": "ulises_3f9a1c7e5b2d40819ac6e3f7b0d5a812", "productId": "65f1c2a4b9d84e37a0c5119f", "licenseKey": "ULS-XXXX-XXXX-XXXX", "hwid": "9A2B7C1D-44E5-4F60-8B9A-0C1D2E3F4A5B", "nonce": "b3f1c8d2a9e04756", "version": "1.4.2"}'The signed token
Every 200 response carries a compact JWS. Its signature is produced with a private key that never leaves our infrastructure, so verifying it locally proves the data you just parsed came from Ulises Licenses and was not rewritten by anything in between. Verification is a page of code in any language.
UlisesLib.jar does the same validation for you, with retries, HWID collection and the auto-updater built in. It is a dependency you shade into your jar rather than a contract you implement.
Using the SDKEndpoint questions
Do I need UlisesLib to use the endpoint?
No. The endpoint is plain HTTPS with a JSON body and a JSON response. Any runtime with an HTTP client and a JSON parser can use it.
Does the endpoint enforce the same rules as the SDK?
Yes. License status, expiry, HWID binding, HWID limits and IP limits are all applied server side, and both paths return the same data tree.
What does the endpoint not give me?
The built-in updater, the checksum verifier and HWID collection. updateInfo tells you that a newer version exists, nothing more. Use UlisesLib if you want those.
Is the endpoint safe to call from an obfuscated or native build?
Yes, that is one of the main reasons it exists. The call lives in your code, and the response is signed so a patched or proxied response cannot be passed off as ours.
Built by Ulises - Citymoon Dynamics