API-Referenz

Einführung

Die PWF-Auth-API ist nach REST aufgebaut. Alle Anfragen und Antworten sind JSON über HTTPS. Es gibt drei Endpunkt-Familien:

• Client-API (/api/auth/*, /api/update/*) — aus deiner ausgelieferten Anwendung mit dem App-Secret aufgerufen.
• Admin-API (/api/admin/*) — Schlüssel- & App-Verwaltung, per Bearer-Token authentifiziert.
• Kunden-/Reseller-API (/api/customer/*, /api/reseller/*) — Self-Service-Portale.

Alle Pfade unten sind relativ zu dieser Basis-URL. Jeder Endpunkt erfordert HTTPS; reine HTTP-Anfragen werden umgeleitet.

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.

Authentifizierung

Client-Endpunkte — App-Secret

Sende das App-Secret im X-App-Secret-Header. Du findest es im Dashboard → deine App. Das Secret bestimmt, zu welcher Anwendung eine Anfrage gehört.

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-Endpunkte — Bearer-Token

Authentifiziere dich an /api/admin/login.php, um ein JWT zu erhalten, und sende es bei jedem Admin-Aufruf als Authorization: Bearer <token>.

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"

Der verschlüsselte Umschlag

SDK-Endpunkte tauschen statt Klartext-JSON einen AES-256-CBC + HMAC-SHA256-Umschlag aus. Das Wire-Format ist {"p": base64(IV || ciphertext), "t": unix_timestamp, "s": hmac_sha256_hex(p + t)} — Verschlüsselungs- und MAC-Schlüssel werden beide aus deinem App-Secret abgeleitet, ein zusätzlicher Schlüsselaustausch ist nicht nötig.

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

Endpunkte mit App-Secret + verschlüsselter Umschlag verlangen ihn in der Anfrage und antworten verschlüsselt. check-key.php erkennt automatisch: Sende einfaches JSON und du bekommst einfaches JSON zurück (deshalb funktionieren die curl-Beispiele auf dieser Seite); sende einen Umschlag und die Antwort kommt verschlüsselt.

Umschläge, die älter als ±300 Sekunden sind, werden abgelehnt — halte die Client-Uhr also einigermaßen genau. Du musst das nie von Hand bauen: Die Open-Source-Beispielclients (VB.NET, C#, Python) bringen eine fertige CryptoEnvelope-Implementierung mit.

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:

Antworten & Fehler

Jede Antwort enthält ein boolesches success. Fehler ergänzen eine menschliche message und einen stabilen, maschinenlesbaren error_code:

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

HTTP-Statuscodes

Rate-Limits & Fair Use

Es gibt kein pauschales Anfragekontingent, aber einige Missbrauchsschutz-Mechanismen sind aktiv:

• Admin-Login ist gegen Brute-Force geschützt — wiederholte Fehlversuche sperren das Konto vorübergehend.
• Testversionen sind pro Gerät (HWID) und pro IP begrenzt; Überschreitungen liefern TRIAL_LIMIT.
• Secret-Regenerierung ist pro App rate-limitiert, um versehentliche Rotationsschleifen zu stoppen.
• Halte Heartbeats im Intervall, das die Login-Antwort vorgibt (Standard 30 s) — schnelleres Feuern bringt nichts.

Schnellstart

Die minimale Integration: validiere einen Schlüssel beim App-Start und halte die Sitzung dann per Heartbeat am Leben.

# 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

Lizenzen & Sitzungen

{
  "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
  }
}

Kostenlose Testversionen

{
  "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": "…" }
}

Benutzerkonten

Lieber Benutzername/Passwort statt roher Schlüssel? PWF Auth liefert ein vollständiges Kontomodell mit bcrypt-Hashing und HWID-Bindung.

App-Inhalte & Fernsteuerung

Über diese Endpunkte zieht deine ausgelieferte App Inhalte, die du live im Panel bearbeitest — Texte, Slides, Preise, Changelog — ohne ein Update zu veröffentlichen.

OTA-Updates

{
  "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

Serverseitige Endpunkte zur Verwaltung von Apps und Schlüsseln. Alle erfordern ein Authorization: Bearer-Token vom Login-Endpunkt unten.

Du willst dein Passwort nicht in einem Skript speichern? Erzeuge im Panel unter Profil → API Tokens ein Personal Access Token und nutze es als Bearer-Wert (pwf_…). Es läuft nie ab, bis du es widerrufst, funktioniert mit jedem /api/admin/*-Endpunkt und ist konstruktionsbedingt von der Verwaltung von Zugangsdaten (Passwort, E-Mail, 2FA, weitere Tokens) ausgeschlossen.

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}'

Die Admin-Oberfläche deckt außerdem apps, sessions, updates, feature-flags, webhooks, analytics, audit, resellers und mehr ab — jeweils unter /api/admin/ mit derselben Bearer-Auth. Melde dich im Dashboard an, um sie zu erkunden.

SDKs

Die REST-API funktioniert aus allem, was eine HTTP-Anfrage senden kann. Offizielle Ein-Datei-SDKs gibt es für VB.NET / C#, mit erstklassigen Beispielen für Python und PHP. Alles andere — Node, Go, Rust, Java, Swift — spricht mit denselben JSON-Endpunkten oben.

• Open-Source-Beispielclients (VB.NET · C# · Python) — komplette Login/Heartbeat/Umschlag-Flows, fertig zum Kopieren
• Quick Start im Panel — 5 geführte Schritte erzeugen funktionierende Snippets in 9 Sprachen mit deinen echten Zugangsdaten
• OpenAPI 3.1 spec (openapi.json) — one-click import into Postman / Insomnia, or feed it to your code generator