API Referansı

Giriş

PWF Auth API'si REST etrafında düzenlenmiştir. Tüm istekler ve yanıtlar HTTPS üzerinden JSON'dur. Üç uç nokta ailesi vardır:

• İstemci API (/api/auth/*, /api/update/*) — dağıttığınız uygulamadan, uygulamanızın secret'ıyla çağrılır.
• Admin API (/api/admin/*) — anahtar ve uygulama yönetimi, Bearer token ile doğrulanır.
• Müşteri / bayi API (/api/customer/*, /api/reseller/*) — self servis portallar.

Aşağıdaki tüm yollar bu temel URL'ye görelidir. Her uç nokta HTTPS gerektirir; düz HTTP istekleri yönlendirilir.

Prefer machines? The whole surface is described in openapi.json (OpenAPI 3.1) — import it into Postman, Insomnia, or a code generator.

API and platform changes are announced in the changelog — breaking changes are always flagged there first.

Kimlik doğrulama

İstemci uç noktaları — App Secret

Uygulamanızın secret'ını X-App-Secret başlığında gönderin. Panel → uygulamanız içinde bulabilirsiniz. Secret, isteğin hangi uygulamaya ait olduğunu belirler.

curl https://pwfauth.com/api/auth/check-key.php \
  -H "X-App-Secret: 9f02532d9c60…  # 64-char hex, from your dashboard" \
  -H "Content-Type: application/json" \
  -d '{"license_key":"XXXXX-XXXXX-XXXXX-XXXXX"}'

Admin uç noktaları — Bearer token

JWT almak için /api/admin/login.php ile kimlik doğrulayın, sonra her admin çağrısında Authorization: Bearer <token> olarak gönderin.

TOKEN=$(curl -s https://pwfauth.com/api/admin/login.php \
  -d '{"username":"admin","password":"…"}' | jq -r .token)

curl https://pwfauth.com/api/admin/keys.php \
  -H "Authorization: Bearer $TOKEN"

Şifreli zarf

SDK düzeyindeki uç noktalar düz JSON yerine AES-256-CBC + HMAC-SHA256 zarfı kullanır. Hat biçimi: {"p": base64(IV || ciphertext), "t": unix_timestamp, "s": hmac_sha256_hex(p + t)} — şifreleme ve MAC anahtarlarının ikisi de app secret'ınızdan türetilir, ekstra anahtar değişimi gerekmez.

{
  "p": "aXYxNmJ5dGVzY2lwaGVydGV4dA…",   // base64( IV || AES-256-CBC ciphertext )
  "t": 1785671000,                       // unix timestamp (±300s accepted)
  "s": "b7fd09…"                        // hmac_sha256_hex( p + t, mac_key )
}

App secret + şifreli zarf işaretli uç noktalar bunu istek için zorunlu tutar ve yanıtı da şifreli döndürür. check-key.php otomatik algılar: düz JSON gönderirseniz düz JSON alırsınız (bu sayfadaki curl örnekleri bu yüzden çalışır); zarf gönderirseniz yanıt şifrelenir.

±300 saniyeden eski zarflar reddedilir; istemci saatini makul ölçüde doğru tutun. Bunu elle yazmanız asla gerekmez: açık kaynak örnek istemciler (VB.NET, C#, Python) hazır bir CryptoEnvelope uygulamasıyla gelir.

How the envelope is built

Both directions use the same recipe. Two keys are derived from your app secret, so every app gets distinct encryption and signing keys:

enc_key = SHA256("enc:" + app_secret)          # 32 bytes
mac_key = SHA256("mac:" + app_secret)          # 32 bytes

# client → server (and server → client — same recipe)
iv = random_bytes(16)
ct = AES-256-CBC(enc_key, iv, json_body)       # PKCS#7 padding
p  = base64(iv || ct)
t  = unix_time()                               # ±300 s accepted
s  = hex(HMAC-SHA256(p + str(t), mac_key))
send { "p": p, "t": t, "s": s }

# receiving: verify s FIRST (constant-time), check |now - t| ≤ 300,
# then base64-decode p, split off the 16-byte IV, decrypt the rest.

Which endpoints require it

Each endpoint card carries a colour-coded auth pill; this table is the same information at a glance:

Yanıtlar ve hatalar

Her yanıt bir boolean success taşır. Hatalar; insan için bir message ve makine için kararlı bir error_code ekler:

{
  "success": false,
  "message": "This license key has been banned.",
  "error_code": "BANNED"
}

HTTP durum kodları

Hız sınırları ve adil kullanım

Genel bir istek kotası yok, ancak birkaç kötüye kullanım koruması aktif:

• Admin girişi brute-force korumalıdır — tekrarlanan başarısızlıklar hesabı geçici kilitler.
• Denemeler cihaz (HWID) ve IP başına sınırlıdır; aşınca TRIAL_LIMIT döner.
• Secret yenileme, yanlışlıkla dönen rotasyon döngülerini durdurmak için uygulama başına hız sınırlıdır.
• Heartbeat'leri login yanıtının verdiği aralıkta tutun (varsayılan 30 sn) — daha sık göndermenin faydası yok.

Hızlı başlangıç

Minimum entegrasyon: uygulamanız açılırken anahtarı doğrulayın, sonra oturumu canlı tutmak için heartbeat gönderin.

# Validate a key from the terminal (plain JSON works here)
curl -X POST https://pwfauth.com/api/auth/check-key.php \
  -H "X-App-Secret: $APP_SECRET" \
  -d '{"license_key":"XXXXX-XXXXX-XXXXX-XXXXX"}'
# → { "success": true, "valid": true, "key": { "status": "active", … } }

The same flow with an official SDK

Login, heartbeat and the server-side kill switch in a few lines — the SDK handles the encrypted envelope for you:

// dotnet add package PWFAuth
using PWFAuth;

var client = new PwfClient(APP_SECRET);
client.SessionEnded += (s, e) =>              // ban / pause / expiry / revoke / offline
{
    Console.WriteLine($"{e.ErrorCode}: {e.Message}");
    Environment.Exit(0);
};

var login = await client.LoginAsync("XXXXX-XXXXX-XXXXX-XXXXX");
if (!login.Success) { Console.WriteLine(login.Message); return; }

client.StartHeartbeat();   // keeps the session alive AND enforces the kill switch

' dotnet add package PWFAuth
Dim client As New PwfClient(APP_SECRET)
AddHandler client.SessionEnded, Sub(s, e)     ' ban / pause / expiry / revoke / offline
                                    MessageBox.Show(e.Message)
                                    Application.Exit()
                                End Sub

Dim login = Await client.LoginAsync("XXXXX-XXXXX-XXXXX-XXXXX")
If login.Success Then client.StartHeartbeat()

# pip install pwfauth
import sys
from pwfauth import PwfClient

client = PwfClient(APP_SECRET)
client.on_session_ended = lambda code, msg: sys.exit(msg)   # kill switch

login = client.login("XXXXX-XXXXX-XXXXX-XXXXX")
if not login.success:
    sys.exit(login.message)

client.start_heartbeat()   # keeps the session alive AND enforces the kill switch

// npm install pwfauth
import { PwfClient } from 'pwfauth';

const client = new PwfClient(process.env.PWFAUTH_SECRET);
client.on('sessionEnded', ({ errorCode, message }) => {     // kill switch
    console.error(`${errorCode}: ${message}`);
    process.exit(1);
});

const login = await client.login('XXXXX-XXXXX-XXXXX-XXXXX');
if (!login.success) { console.error(login.message); process.exit(1); }

client.startHeartbeat();   // keeps the session alive AND enforces the kill switch

Lisanslar ve oturumlar

{
  "success": true,
  "session_id": "8f2c…",
  "user": {
    "license_key": "XXXXX-XXXXX-XXXXX-XXXXX",
    "key_type": "days", "duration": 30,
    "expires_at": "2026-09-01T12:00:00Z",
    "days_remaining": 30, "status": "active"
  },
  "features": { "pro_tier": true },
  "heartbeat_interval": 30
}

{ "success": true, "message": "Heartbeat received" }

// the moment the key is banned / paused / expired / reset, the SAME call answers:
{ "success": false, "error_code": "BANNED",
  "message": "This license key has been banned." }   // session is dropped — log the user out

curl -X POST https://pwfauth.com/api/auth/check-key.php \
  -H "X-App-Secret: $APP_SECRET" \
  -d '{"license_key":"XXXXX-XXXXX-XXXXX-XXXXX"}'

var http = new HttpClient();
http.DefaultRequestHeaders.Add("X-App-Secret", APP_SECRET);
var res = await http.PostAsync("https://pwfauth.com/api/auth/check-key.php",
    new StringContent("{\"license_key\":\"XXXXX-XXXXX-XXXXX-XXXXX\"}"));

import urllib.request, json
req = urllib.request.Request("https://pwfauth.com/api/auth/check-key.php",
    data=json.dumps({"license_key": "XXXXX-XXXXX-XXXXX-XXXXX"}).encode(),
    headers={"X-App-Secret": APP_SECRET})
print(json.load(urllib.request.urlopen(req)))

const res = await fetch('https://pwfauth.com/api/auth/check-key.php', {
  method: 'POST',
  headers: { 'X-App-Secret': process.env.APP_SECRET },
  body: JSON.stringify({ license_key: 'XXXXX-XXXXX-XXXXX-XXXXX' })
});
console.log(await res.json());

$ch = curl_init('https://pwfauth.com/api/auth/check-key.php');
curl_setopt_array($ch, [CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-App-Secret: ' . $APP_SECRET],
    CURLOPT_POSTFIELDS => '{"license_key":"XXXXX-XXXXX-XXXXX-XXXXX"}']);
$res = json_decode(curl_exec($ch), true);

{
  "success": true, "valid": true,
  "key": {
    "status": "active", "key_type": "days", "duration": 30,
    "activated_at": "2026-08-02T12:00:00Z",
    "expires_at": "2026-09-01T12:00:00Z",
    "days_remaining": 30, "max_devices": 1
  }
}

Ücretsiz Denemeler

{
  "success": true, "message": "Trial activated! You have 3 days.",
  "trial_key": "TRIAL-1A2B3-C4D5E-F6A7B",
  "session_id": "8f2c…",
  "expires_at": "2026-08-23T12:00:00Z", "days_remaining": 3,
  "user": { "key_type": "days", "status": "active", … },
  "app":  { "name": "…", "version": "…" }
}

Kullanıcı hesapları

Ham anahtarlar yerine kullanıcı adı/şifre girişini mi tercih ediyorsunuz? PWF Auth, bcrypt karma ve HWID bağlamalı eksiksiz bir hesap modeliyle gelir.

Uygulama İçeriği ve Uzaktan Yönetim

Bu uç noktalar, dağıttığınız uygulamanın panelde canlı düzenlediğiniz içeriği — metinler, slaytlar, fiyatlandırma, değişiklik günlüğü — güncelleme yayınlamadan çekmesini sağlar.

OTA güncellemeleri

{
  "success": true, "update_available": true,
  "update": {
    "version": "1.4.0", "channel": "stable",
    "is_mandatory": false, "file_size": 5242880,
    "sha256": "…", "changelog": "…",
    "download_url": "api/update/download.php?v=1.4.0"
  }
}

Webhooks

Turn events into HTTP calls to your server: key activations, bans, expiries, orders, new updates and more. Configure destinations per app (or for all apps) in the panel under Application → Webhooks, pick the events you care about, and PWF Auth POSTs a signed JSON body to your URL. Delivery is queue-based — expect it within a minute or two of the event, not in the same instant.

Delivery payload

{
  "event": "key.activated",
  "timestamp": "2026-08-20T14:07:02Z",
  "data": {
    "app_id": "01af6643-…",
    "license_key": "XXXXX-XXXXX-XXXXX-XXXXX",
    "hwid": "A1B2C3…"
  }
}

Delivery headers

Verifying the signature

Always verify before trusting a delivery: compute the V2 MAC over timestamp + "." + raw body with your endpoint secret, compare in constant time, and reject stale timestamps (±5 minutes is plenty). Answer 2xx fast — heavy work belongs in your own queue.

// X-Webhook-Signature-V2: t=<ts>,v1=<hex>
[$t, $v1] = explode(',', $_SERVER['HTTP_X_WEBHOOK_SIGNATURE_V2'] ?? ',');
$t = substr($t, 2);  $v1 = substr($v1, 3);
$raw = file_get_contents('php://input');

$ok = hash_equals(hash_hmac('sha256', $t . '.' . $raw, $secret), $v1)
   && abs(time() - (int)$t) < 300;
if (!$ok) { http_response_code(400); exit; }
http_response_code(200);   // answer fast — queue heavy work

// X-Webhook-Signature-V2: t=<ts>,v1=<hex>
const [t, v1] = req.headers['x-webhook-signature-v2']
    .split(',').map(kv => kv.split('=')[1]);
const mac = crypto.createHmac('sha256', secret)
    .update(`${t}.${rawBody}`).digest('hex');

const ok = crypto.timingSafeEqual(Buffer.from(mac), Buffer.from(v1))
        && Math.abs(Date.now() / 1000 - Number(t)) < 300;
res.sendStatus(ok ? 200 : 400);   // answer fast — queue heavy work

# X-Webhook-Signature-V2: t=<ts>,v1=<hex>
import hmac, time
t, v1 = (kv.split("=", 1)[1]
         for kv in request.headers["X-Webhook-Signature-V2"].split(","))
mac = hmac.new(secret, f"{t}.{raw_body}".encode(), "sha256").hexdigest()

ok = hmac.compare_digest(mac, v1) and abs(time.time() - int(t)) < 300
return ("", 200) if ok else ("", 400)   # answer fast — queue heavy work

Retries & failure policy

• A delivery counts as successful on any 2xx/3xx answered within 5 seconds.
• Failures retry up to 5 attempts with widening gaps: 1 m → 5 m → 30 m → 2 h → 6 h.
• X-Webhook-Id is minted once per event and reused on every retry — idempotency is one seen? lookup away.
• A destination that fails 20 times in a row is paused automatically; re-enable it from the panel (a test event button is right there).

Events

Subscribe to specific events or leave the filter empty to receive them all. event in the body tells you which one fired:

Admin API

Uygulama ve anahtar yönetimi için sunucu tarafı uç noktalar. Hepsi aşağıdaki login uç noktasından alınan Authorization: Bearer token'ı gerektirir.

Şifrenizi bir betikte saklamak istemiyor musunuz? Panel → Profil → API Token'ları bölümünden bir Personal Access Token üretin ve Bearer değeri olarak kullanın (pwf_…). Siz iptal edene kadar süresi dolmaz, her /api/admin/* uç noktasında çalışır ve tasarım gereği kimlik bilgisi yönetiminden (şifre, e-posta, 2FA, yeni token üretme) men edilmiştir.

curl -X POST https://pwfauth.com/api/admin/keys.php \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"app_id":"01af6643-cf3a-4280-b9ce-cb5fa8ae987c",
       "count":100,"key_type":"days","duration_value":30}'

Admin yüzeyi ayrıca apps, sessions, updates, feature-flags, webhooks, analytics, audit, resellers ve fazlasını kapsar — hepsi /api/admin/ altında, aynı Bearer doğrulamasıyla. Keşfetmek için panele giriş yapın.

SDK'lar

REST API, HTTP isteği gönderebilen her şeyden çalışır. VB.NET / C# için resmî tek dosyalık SDK'lar; Python ve PHP için birinci sınıf örnekler mevcut. Geri kalan her şey — Node, Go, Rust, Java, Swift — yukarıda belgelenen aynı JSON uç noktalarıyla konuşur.

• Açık kaynak örnek istemciler (VB.NET · C# · Python) — tam login/heartbeat/zarf akışları, kopyalamaya hazır
• Panel içi Quick Start — gerçek kimlik bilgilerinizle 9 dilde çalışan parçacıklar üreten 5 rehberli adım
• OpenAPI 3.1 spec (openapi.json) — one-click import into Postman / Insomnia, or feed it to your code generator