🌊 OceanAC

API & integration

How the anticheat plugin talks to oceanac.esoxxii.cc. Base URL for every call below is https://oceanac.esoxxii.cc/api/v1.

1. The licence key

Each customer gets one key, shaped OAC-XXXX-XXXX-XXXX-XXXX. It goes in the plugin config:

license:
  key: "OAC-XXXX-XXXX-XXXX-XXXX"
  # optional: a human name for this server, shown in the panel
  server-name: "PvP-1"

The key authenticates every request as Authorization: Bearer <key>. It is stored on the panel only as a SHA-256 hash — a database leak never reveals a working key.

2. Handshake — on start

POST /handshake. The plugin blocks on the answer: it may run only if the licence is active and has room for this server.

POST /api/v1/handshake
Authorization: Bearer OAC-...
Content-Type: application/json

{ "fingerprint": "<stable host hash>", "name": "PvP-1",
  "version": "1.0.0", "mcVersion": "1.21.4" }

→ 200 { "ok": true, "plan": "network", "graceHours": 72, "token": "<token>" }
→ 402 unknown key   403 suspended/expired   409 server limit reached

Send the returned token back on later calls. The plugin keeps running through a brief panel outage on its own; you do not need to handle that.

3. Heartbeat — every ~60s

POST /heartbeat. Liveness, and the performance figures the panel's server view shows.

{ "fingerprint": "...", "players": 42, "tps": 19.9, "msPerTick": 0.4 }

4. Events — batched

POST /events. Flags and punishments, buffered by the plugin and posted together so a busy server is not one request per flag.

{ "fingerprint": "...",
  "flags": [ { "uuid": "...", "name": "Steve", "check": "KillAuraI",
              "category": "combat", "vl": 12, "severity": 0.8,
              "debug": "confidence=61 ...", "time": 1737400000000 } ],
  "punishments": [ { "uuid": "...", "name": "Steve", "type": "ban",
                     "reason": "Gameplay analysis", "check": "KillAuraI" } ] }

Each flag also appears on the panel's live feed the instant it lands.

5. Cross-server sync — on join

GET /sync/player/<uuid>. What every other server on the same licence already knows about this player, so a cheater caught on one server arrives at the next already under suspicion.

→ { "ok": true, "totalFlags": 34, "bannedElsewhere": true,
    "checks": [ { "check": "KillAuraI", "count": 20, "severity": 0.9 } ] }

6. Evidence upload — on ban

POST /recording. The movement bundle behind a ban, so the panel can replay the path that caused it.

{ "fingerprint": "...", "uuid": "...", "name": "Steve",
  "check": "ElytraB", "format": "oceanac-tsv-1", "ticks": 200,
  "body": "<the .tsv, verbatim>" }

Failure handling, in one line each