เอกสารสำหรับนักพัฒนา

Authorization: Bearer kt_live_xxxxxxxxxxxx

curl -X POST https://api.keythai.net/v1/licenses/KEYT-AB12-3C4D-5E6F-7G8H-9J0K/activate \
  -H "Authorization: Bearer kt_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "fingerprint": "a1b2c3d4e5f6...",
    "name": "เครื่องของสมชาย",
    "platform": "windows",
    "hostname": "DESKTOP-1234"
  }'

{
  "valid": true,
  "status": "active",
  "expires_at": 1767225600,
  "machine_count": 1,
  "max_activations": 3,
  "policy": { "type": "subscription", "offline_allowed": true },
  "issued_at": 1717286400,
  "nonce": "8f3a...",
  "signature": "base64-ed25519-signature..."
}

curl -X POST https://api.keythai.net/v1/licenses/KEYT-AB12-3C4D-5E6F-7G8H-9J0K/validate \
  -H "Authorization: Bearer kt_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "fingerprint": "a1b2c3d4e5f6..." }'

curl -X POST https://api.keythai.net/v1/licenses/KEYT-AB12-3C4D-5E6F-7G8H-9J0K/deactivate \
  -H "Authorization: Bearer kt_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "fingerprint": "a1b2c3d4e5f6..." }'

curl -X POST https://api.keythai.net/v1/licenses/KEYT-AB12-3C4D-5E6F-7G8H-9J0K/heartbeat \
  -H "Authorization: Bearer kt_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "fingerprint": "a1b2c3d4e5f6..." }'

curl https://api.keythai.net/v1/keys \
  -H "Authorization: Bearer kt_live_xxxxxxxxxxxx"

{
  "keys": [
    {
      "kid": "key-2024-01",
      "alg": "EdDSA",
      "publicJwk": {
        "kty": "OKP",
        "crv": "Ed25519",
        "x": "11qYAYKxCrfVS_7TyWQHOg7hcvPapiMlrwIaaPcHURo"
      }
    }
  ]
}

curl -X POST https://api.keythai.net/v1/licenses \
  -H "Authorization: Bearer kt_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "product": "my-app",
    "policyId": "01J...",
    "holderName": "สมชาย",
    "holderEmail": "somchai@example.com",
    "metadata": {"order": "INV-001"},
    "quantity": 1
  }'

# 201 → { "licenses": [{ "key": "KEYT-AB12-....", "id", "key_prefix",
#         "key_last4", "status", "expires_at", "max_activations" }] }
# "key" คือ plaintext — แสดงครั้งเดียว! เกินโควตาแผน → 403 QUOTA_EXCEEDED

curl "https://api.keythai.net/v1/licenses?status=active&q=somchai&page=1&limit=25" \
  -H "Authorization: Bearer kt_live_xxxxxxxxxxxx"
# q ค้นจาก key_prefix / key_last4 / holderName / holderEmail
# → { "data": [...ไม่มี plaintext key...], "total", "page", "limit" }

curl -X PATCH https://api.keythai.net/v1/licenses/KEYT-AB12-3C4D-5E6F-7G8H-9J0K \
  -H "Authorization: Bearer kt_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"action": "suspend"}'
# action: suspend | resume | revoke (revoke = ถาวร แก้อีกไม่ได้)
# หรือแก้ field: {"holderName", "holderEmail", "metadata", "expiresAt"}

curl -X DELETE "https://api.keythai.net/v1/licenses/KEYT-AB12-3C4D-5E6F-7G8H-9J0K/machines/a1b2c3d4..." \
  -H "Authorization: Bearer kt_live_xxxxxxxxxxxx"
# → { "ok": true, "machine_count": N }

# ใช้หา id ของ product/policy ก่อนสร้าง license
curl https://api.keythai.net/v1/products -H "Authorization: Bearer kt_live_..."
curl "https://api.keythai.net/v1/policies?productId=01J..." -H "Authorization: Bearer kt_live_..."

curl "https://api.keythai.net/v1/entitlements?productId=01J..." \
  -H "Authorization: Bearer kt_live_xxxxxxxxxxxx"
# productId เลือกใส่ได้ (ไม่ใส่ = ทุก product ของ tenant) — เรียงตาม code
# → { "data": [{ "id", "product_id", "code", "name", "created_at" }, ...] }

curl -X POST https://api.keythai.net/v1/entitlements \
  -H "Authorization: Bearer kt_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "productId": "01J...", "code": "export.pdf", "name": "ส่งออก PDF" }'

# 201 → { "id", "product_id", "code", "name", "created_at" }
# code: a-z 0-9 _ : - ยาว 1-64 ตัว — ซ้ำใน product เดิม → 409 VALIDATION_ERROR

curl -X DELETE https://api.keythai.net/v1/entitlements/01J... \
  -H "Authorization: Bearer kt_live_xxxxxxxxxxxx"
# → { "ok": true }  (grant ใน policy ที่อ้าง entitlement นี้ถูกลบตามแบบ cascade)

# กำหนดชุด entitlement ของ policy แบบ "แทนที่ทั้งชุด" (replace set)
curl -X PUT https://api.keythai.net/v1/policies/01J.../entitlements \
  -H "Authorization: Bearer kt_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "entitlementIds": ["01Jent1...", "01Jent2..."] }'

# → { "ok": true, "entitlement_ids": [...] }
# entitlementIds: [] = ล้าง grant ทั้งหมด; ทุก id ต้องอยู่ใน product เดียวกับ policy
# จากนั้น license ของ policy นี้จะพก codes เหล่านี้ใน payload ที่เซ็น (activate/validate)

{
  "valid": true,
  "status": "active",
  "expires_at": 1767225600,
  "machine_count": 1,
  "max_activations": 3,
  "policy": { "type": "subscription", "offline_allowed": true },
  "issued_at": 1717286400,
  "nonce": "8f3a...",
  "entitlements": ["export.pdf", "premium"],
  "signature": "base64-ed25519-signature..."
}

// JS/TS (keythai-sdk)
import { hasEntitlement } from "keythai-sdk";
if (hasEntitlement(lic.payload, "export.pdf")) enablePdfExport();

# Python (keythai)
from keythai import has_entitlement
if has_entitlement(lic["payload"], "export.pdf"):
    enable_pdf_export()

// C# (KeyThai.Client)
if (KeyThaiVerifier.HasEntitlement(lic.Payload, "export.pdf"))
    EnablePdfExport();

{
  "error": {
    "code": "SEAT_LIMIT_REACHED",
    "message": "เปิดใช้งานครบจำนวนเครื่องสูงสุดแล้ว"
  }
}

import { canonicalJson } from "@keythai/shared"; // หรือคัดลอกฟังก์ชันลงในแอป

// payload = response โดยตัด field "signature" ออก
const { signature, ...payload } = res;
const message = new TextEncoder().encode(canonicalJson(payload));
const sig = Uint8Array.from(atob(signature), (c) => c.charCodeAt(0));

const key = await crypto.subtle.importKey(
  "jwk", publicJwk, { name: "Ed25519" }, false, ["verify"],
);
const ok = await crypto.subtle.verify({ name: "Ed25519" }, key, sig, message);

// .lic = base64( JSON.stringify({ payload, signature, kid }) )
const decoded = JSON.parse(atob(licFileContents));
// decoded.payload คือ SignedLicensePayload
// 1) verify decoded.signature เทียบกับ canonicalJson(decoded.payload) + public key ที่ฝังไว้
// 2) ตรวจ payload.expires_at เทียบเวลาปัจจุบัน
// 3) ตรวจ fingerprint ของเครื่องตรงกับที่อนุญาตหรือไม่

{
  "id": "whd_01J...",
  "event": "license.activated",
  "created_at": 1717286400,
  "data": {
    "license": {
      "id": "lic_01J...",
      "key_prefix": "KEYT-AB12",
      "status": "active",
      "product_id": "prd_01J...",
      "expires_at": 1767225600
    }
  }
}

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

function verifyKeyThaiWebhook(rawBody, signatureHeader, secret) {
  const expected = "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex");
  return timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader));
}

// JS/TS (keythai-sdk)
const stopper = client.startAutoHeartbeat(key, fingerprint, {
  intervalSeconds: 60, // ค่าเริ่มต้น 300; อ่านจาก listPolicies() → heartbeat_interval_seconds
  onBeat: (res) => console.log("alive:", res.status),
  onError: (err) => console.warn("heartbeat failed:", err),
});
// เมื่อปิดแอป:
stopper.stop(); // idempotent

# Python (keythai)
handle = client.start_auto_heartbeat(
    key, fp,
    interval_seconds=None,   # None → policy heartbeat_interval_seconds มิฉะนั้น 300s
    on_beat=lambda res: print("beat ok"),
    on_error=lambda exc: print("heartbeat failed:", exc),
)
handle.stop()                # idempotent (หรือ client.stop_auto_heartbeat())

// C# (KeyThai.Client)
IDisposable beat = client.StartAutoHeartbeat(
    key, fingerprint,
    interval: TimeSpan.FromSeconds(60), // null → policy heartbeat_interval_seconds มิฉะนั้น 300s
    onBeat: r  => Console.WriteLine($"beat #{r.BeatNumber}"),
    onError: ex => Console.WriteLine($"error: {ex.Message}"));
beat.Dispose();   // หยุด loop (หรือเมื่อ client ถูก dispose)