REST API

REST API v1 ile sunucu, ihlal, oyuncu ve ceza verilerine kendi araçlarınızdan (Discord botu, web siteniz, raporlama) erişebilirsiniz. API anahtarları Pro ve Network planlarında kullanılabilir.

Kimlik doğrulama

Entegrasyonlar → API anahtarları bölümünden bir anahtar oluşturun ve her istekte gönderin:

curl https://wardenguard.pro/api/v1/servers \
  -H "Authorization: Bearer wg_live_..."

Anahtar yalnızca oluşturulduğunda bir kez gösterilir ve sunucuda hash'lenmiş olarak saklanır. Anahtar başına dakikada 120 istek sınırı vardır; aşıldığında 429 döner.

Kapsamlar

Kapsam	İzin verdiği uçlar
`read:servers`	`GET /api/v1/servers`
`read:violations`	`GET /api/v1/servers/:id/violations`
`read:players`	`GET /api/v1/servers/:id/players`
`read:punishments`	`GET /api/v1/servers/:id/punishments`
`write:actions`	`POST /api/v1/servers/:id/players/:uuid/actions`

Uçlar

Sunucular

GET /api/v1/servers

İhlaller

GET /api/v1/servers/:id/violations?limit=50&before=1730000000000&player=<uuid>

Yanıt en yeni ihlalden başlar; next değerini sonraki isteğin before parametresi olarak kullanın.

Oyuncular ve cezalar

GET /api/v1/servers/:id/players?status=online&page=1&pageSize=50
GET /api/v1/servers/:id/punishments?page=1&pageSize=50

Oyuncu aksiyonu

curl -X POST https://wardenguard.pro/api/v1/servers/SERVER_ID/players/UUID/actions \
  -H "Authorization: Bearer wg_live_..." \
  -H "Content-Type: application/json" \
  -d '{"action":"tempban","reason":"Hile","durationMs":604800000}'

action: kick, ban, tempban, unban, mute, unmute, freeze, unfreeze, exempt, unexempt, reset_vl, message, watch, unwatch. Sunucu çevrimdışıysa aksiyon 5 dakika kuyrukta bekler (delivery: "queued").

Hatalar

Tüm hatalar aynı biçimdedir:

{ "error": { "code": "MISSING_SCOPE", "message": "API key is missing scope: read:players" } }

Webhook imzası

Genel webhook'lar X-WardenGuard-Signature başlığıyla imzalanır. Doğrulama (Node.js):

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(secret, timestamp, rawBody, signature) {
  const expected = "sha256=" + createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
  const ok = expected.length === signature.length && timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
  const fresh = Math.abs(Date.now() - Number(timestamp)) < 5 * 60 * 1000;
  return ok && fresh;
}

timestamp değeri X-WardenGuard-Timestamp başlığındadır.

Agent protokolü

Plugin ile panel arasındaki WebSocket protokolü (HMAC imzalı zarf, ack ve yeniden gönderim) depo içindeki docs/PROTOCOL.md dosyasında ayrıntılı olarak belgelenmiştir.