Onyx

Guide & API

How licensing works, how to get set up, and every endpoint.

How licensing works

  • One license = one machine. A key binds to the first machine that activates it (a SHA-256 of the Windows MachineGuid). The transfer tool and the extension/runner share that binding, so a key cannot run on two machines. A second machine is refusedhwid_mismatch; the operator can Unbind to move a key.
  • Signed offline grace. Every successful validate/heartbeat returns an Ed25519- signed entitlement bound to the key and machine, valid for a 72h window. The app verifies it offline with the server public key, so a brief outage does not lock anyone out.
  • Subscriptions. A key can carry an end date; past it, validate/heartbeat returnexpired and the apps stop at the next check.

Getting started

  • Go to Download, enter your key, and grab the launcher and the transfer tool.
  • In the transfer tool, open Settings, paste your key, and click Validate to activate it on this machine.
  • Run the launcher (Onyx.exe) - it installs the Chrome extension for the resale bot automatically, on the same machine and key.
  • New PC? Ask the seller to unbind the key, then activate on the new machine.

Client endpoints

POST /api/validate

Activate on a machine. Binds the HWID on first use, issues a 14-day session. Rate-limited 10/min/IP.

// request
{ "key": "ONYX-AAAA-BBBB-CCCC", "hwid": "<sha256 hex>" }
// 200
{ "ok": true, "session_token": "...", "expires": 1717520000000,
  "plan": "monthly", "entitlement": "<payload>.<sig>" }
// 403  reason: not_found | revoked | expired | hwid_mismatch
{ "ok": false, "reason": "hwid_mismatch" }

POST /api/heartbeat

Keep-alive for the exe session. Single-session check, auto-renews under 24h, refreshes the entitlement.

// request
{ "key": "ONYX-...", "session_token": "...", "hwid": "<sha256 hex>" }
// 200
{ "ok": true, "expires": 1717520000000, "entitlement": "<payload>.<sig>" }
// 403  reason: not_found | revoked | hwid_mismatch | no_session | replaced | expired

POST /api/browser-validate ยท POST /api/browser-heartbeat

Extension/runner session (7 days), bound to the SAME machine HWID as the exe. The worker supplies the HWID on the extension's behalf. Same shapes as above.

GET /api/pubkey

The Ed25519 public key (SPKI base64) for verifying entitlements offline.

{ "pubkey": "MCowBQYDK2Vw..." }

GET /api/version?product=transfer

Latest published version for a product (the app force-updates on a newer mandatory release). Returns { "version": null } if none.

{ "version": "1.0.0", "url": "https://onyx-resell.com/files/OnyxTransfer.exe",
  "changelog": "- ...", "mandatory": true }

GET /api/health

{ "ok": true }

Admin endpoints

All /api/admin/* require Authorization: Bearer <ADMIN_TOKEN>. The admin console wraps them.

  • GET /api/admin/keys - list / inspect
  • POST /api/admin/generate plan, note, days
  • POST /api/admin/set-expiry key, days | expires_at - renew or set the end date
  • POST /api/admin/revoke / reactivate / unbind key
  • POST /api/admin/release product, version, changelog, url, mandatory - publish a version and announce the changelog to Discord
  • POST /api/admin/upload/<name> (raw body) - host a static file (onyx.crx / update.xml / installer) on the volume, served at /files/<name>