Cẩm nang tích hợp APIAPI Integration Handbook

Mọi thứ bạn cần để kích hoạt license, kiểm tra hiệu lực, phân phối bản cập nhật và tự động hoá cấp license từ hệ thống của mình.Everything you need to activate licenses, validate them, ship updates and automate license issuing from your own systems.

MB License Cloud cung cấp gì

What MB License Cloud provides

MB License Cloud là cổng cấp phép (license gateway) tự lưu trữ. Sản phẩm của bạn (plugin WordPress, ứng dụng, dịch vụ) gọi API để kích hoạt license trên một site/thiết bị, sau đó dùng một activation lease ngắn hạn thay cho license key trong mọi lần gọi tiếp theo.

MB License Cloud is a self-hosted license gateway. Your product (a WordPress plugin, an app, a service) calls the API to activate a license on a site or device, then uses a short-lived activation lease instead of the license key for every later call.

Ba nhóm API

Three API families

Base URL & định dạng

Base URL & format

• Base URL là domain bạn triển khai, ví dụ https://license.example.com. Trong bản dev: http://localhost:8080.
• Body là JSON (Content-Type: application/json), tối đa 32 KiB cho runtime API. Runtime API còn chấp nhận application/x-www-form-urlencoded để tương thích bản cũ.
• Thời gian phản hồi dùng RFC 3339; timestamp trong yêu cầu là Unix giây.
• Các alias /wp-json/mb-license/v2/* chỉ phục vụ giai đoạn chuyển đổi; tích hợp mới hãy dùng /api/v2.

• The base URL is the domain you deploy, e.g. https://license.example.com. In the dev stack: http://localhost:8080.
• Bodies are JSON (Content-Type: application/json), up to 32 KiB for the runtime API. The runtime API also accepts application/x-www-form-urlencoded for legacy compatibility.
• Response times use RFC 3339; request timestamps are Unix seconds.
• The /wp-json/mb-license/v2/* aliases exist only for staged migrations; new integrations should use /api/v2.

curl -s https://license.example.com/api/v2/health
# {"ok":true,"service":"mb-license-cloud","version":"1.8.0","time":"…"}

Bắt đầu nhanhQuickstart

Từ con số 0 đến lần kích hoạt đầu tiên trong năm bước.From zero to your first activation in five steps.

1. Triển khai máy chủ. Làm theo README (docker compose up -d --build) và đăng nhập /admin/login.
2. Tạo sản phẩm trong Admin → Products. Ghi lại slug (ví dụ content-studio-pro) — đó là giá trị product trong API.
3. Cấp một license trong Admin → Licenses. License key chỉ hiển thị một lần; hãy sao chép ngay.
4. Ký và gọi activate như ví dụ bên dưới. Lưu lease.token trả về — nó thay thế license key.
5. Gọi check / heartbeat định kỳ bằng lease token để biết license còn hiệu lực.

1. Deploy the server. Follow the README (docker compose up -d --build) and sign in at /admin/login.
2. Create a product in Admin → Products. Note its slug (e.g. content-studio-pro) — it is the product value in the API.
3. Issue a license in Admin → Licenses. The license key is shown once; copy it right away.
4. Sign and call activate as shown below. Store the returned lease.token — it replaces the license key.
5. Call check / heartbeat periodically with the lease token to learn whether the license is still valid.

Lần kích hoạt đầu tiên

Your first activation

// Node.js 18+
const crypto = require('crypto');

const BASE = 'https://license.example.com';
const licenseKey = 'MB-XXXX-XXXX-XXXX-XXXX';        // as issued
const fields = {
  route: 'activate',
  product: 'content-studio-pro',
  site_url: 'https://example.com',                 // already normalized, see Signature v2
  instance_id: '0fd4c1a2e7b94d6f',                  // stable random ID of this installation
  app_version: '4.2.0',
  environment: 'production',
  channel: 'stable',
  transfer_token: '',
};
const ts = Math.floor(Date.now() / 1000);
const nonce = crypto.randomBytes(16).toString('hex');

const canonical = [
  fields.route, fields.product, fields.site_url, fields.instance_id,
  fields.app_version, String(ts), nonce,
  fields.environment, fields.channel, fields.transfer_token,
].join('\n');
// HMAC key = the license key, upper-cased and stripped to A-Z 0-9 and "-"
const key = licenseKey.toUpperCase().replace(/[^A-Z0-9-]/g, '');
const signature = crypto.createHmac('sha256', key).update(canonical).digest('hex');

const res = await fetch(BASE + '/api/v2/activate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    license_key: licenseKey,
    product: fields.product,
    site_url: fields.site_url,
    instance_id: fields.instance_id,
    app_version: fields.app_version,
    environment: fields.environment,
    channel: fields.channel,
    request_ts: ts,
    request_nonce: nonce,
    signature_version: 2,
    request_signature: signature,
  }),
});
const data = await res.json();
console.log(data.valid, data.lease && data.lease.token);

<?php
$base = 'https://license.example.com';
$licenseKey = 'MB-XXXX-XXXX-XXXX-XXXX';
$f = [
  'route' => 'activate', 'product' => 'content-studio-pro',
  'site_url' => 'https://example.com', 'instance_id' => '0fd4c1a2e7b94d6f',
  'app_version' => '4.2.0', 'environment' => 'production',
  'channel' => 'stable', 'transfer_token' => '',
];
$ts = time();
$nonce = bin2hex(random_bytes(16));
$canonical = implode("\n", [
  $f['route'], $f['product'], $f['site_url'], $f['instance_id'],
  $f['app_version'], (string) $ts, $nonce,
  $f['environment'], $f['channel'], $f['transfer_token'],
]);
$key = preg_replace('/[^A-Z0-9-]/', '', strtoupper($licenseKey));
$sig = hash_hmac('sha256', $canonical, $key);

$ch = curl_init("$base/api/v2/activate");
curl_setopt_array($ch, [
  CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode([
    'license_key' => $licenseKey, 'product' => $f['product'],
    'site_url' => $f['site_url'], 'instance_id' => $f['instance_id'],
    'app_version' => $f['app_version'], 'environment' => $f['environment'],
    'channel' => $f['channel'], 'request_ts' => $ts,
    'request_nonce' => $nonce, 'signature_version' => 2,
    'request_signature' => $sig,
  ]),
]);
$data = json_decode(curl_exec($ch), true);
var_dump($data['valid'] ?? false, $data['lease']['token'] ?? null);

import hashlib, hmac, json, re, secrets, time, urllib.request

BASE = "https://license.example.com"
license_key = "MB-XXXX-XXXX-XXXX-XXXX"
f = dict(route="activate", product="content-studio-pro",
         site_url="https://example.com", instance_id="0fd4c1a2e7b94d6f",
         app_version="4.2.0", environment="production",
         channel="stable", transfer_token="")
ts = int(time.time())
nonce = secrets.token_hex(16)
canonical = "\n".join([f["route"], f["product"], f["site_url"], f["instance_id"],
                       f["app_version"], str(ts), nonce,
                       f["environment"], f["channel"], f["transfer_token"]])
key = re.sub(r"[^A-Z0-9-]", "", license_key.upper())
sig = hmac.new(key.encode(), canonical.encode(), hashlib.sha256).hexdigest()

body = {"license_key": license_key, "product": f["product"],
        "site_url": f["site_url"], "instance_id": f["instance_id"],
        "app_version": f["app_version"], "environment": f["environment"],
        "channel": f["channel"], "request_ts": ts, "request_nonce": nonce,
        "signature_version": 2, "request_signature": sig}
req = urllib.request.Request(BASE + "/api/v2/activate",
                             data=json.dumps(body).encode(),
                             headers={"Content-Type": "application/json"})
data = json.load(urllib.request.urlopen(req))
print(data["valid"], data["lease"]["token"])

BASE=https://license.example.com
KEY='MB-XXXX-XXXX-XXXX-XXXX'
TS=$(date +%s)
NONCE=$(openssl rand -hex 16)
CANON=$(printf 'activate\ncontent-studio-pro\nhttps://example.com\n0fd4c1a2e7b94d6f\n4.2.0\n%s\n%s\nproduction\nstable\n' "$TS" "$NONCE")
SIG=$(printf '%s' "$CANON" | openssl dgst -sha256 -hmac "$KEY" -hex | sed 's/^.* //')

curl -sS "$BASE/api/v2/activate" -H 'Content-Type: application/json' -d "{
  \"license_key\":\"$KEY\",\"product\":\"content-studio-pro\",
  \"site_url\":\"https://example.com\",\"instance_id\":\"0fd4c1a2e7b94d6f\",
  \"app_version\":\"4.2.0\",\"environment\":\"production\",\"channel\":\"stable\",
  \"request_ts\":$TS,\"request_nonce\":\"$NONCE\",
  \"signature_version\":2,\"request_signature\":\"$SIG\"}"

Phản hồi thành công (rút gọn)

Successful response (abridged)

{
  "ok": true,
  "valid": true,
  "status": "active",
  "message": "License activated.",
  "request_id": "…",
  "license": { "plan": "pro", "expires_at": "2027-11-12T00:00:00Z",
               "max_activations": 1, "active_activations": 1 },
  "product": { "slug": "content-studio-pro", "current_version": "4.3.0",
               "update_available": true, "entitlements": { } },
  "activation_id": 42,
  "lease": { "token": "mbl_…", "expires_at_ts": 1787166400, "grace_until_ts": 1787425600 },
  "server_time": "2026-11-12T08:00:00Z"
}

Xác thựcAuthentication

Mỗi nhóm API dùng một cơ chế xác thực riêng, phù hợp với nơi nó chạy.Each API family uses its own mechanism, matched to where it runs.

License key và activation lease

License key and activation lease

License key chỉ đi qua mạng trong lần activate (hoặc transfer/claim). Máy chủ chỉ lưu giá trị băm HMAC, rồi trả về một lease ngẫu nhiên gắn với site đó. Các lệnh check, heartbeat, update, deactivate dùng lease token. Nếu lease bị lộ, chỉ một lần kích hoạt bị ảnh hưởng và có thể thu hồi.

The license key crosses the network only for activate (or transfer/claim). The server stores just an HMAC hash and returns a random lease bound to that site. check, heartbeat, update and deactivate use the lease token. If a lease leaks, only one activation is affected and it can be revoked.

Thời hạn lease & chế độ offline

Lease lifetime & offline grace

Lease có hạn (LEASE_TTL, mặc định 24 giờ) cùng thời gian ân hạn (LEASE_GRACE, mặc định 72 giờ). Phản hồi trả lease.expires_at_ts và lease.grace_until_ts. Khi máy chủ không liên lạc được, sản phẩm có thể tiếp tục chạy tới hết grace_until_ts, rồi phải khoá tính năng trả phí.

A lease expires (LEASE_TTL, default 24 h) and has a grace window (LEASE_GRACE, default 72 h). Responses carry lease.expires_at_ts and lease.grace_until_ts. While the server is unreachable your product may keep running until grace_until_ts, after which paid features must lock.

API client (Integration API)

API client (Integration API)

Tạo trong Admin → API Clients. Mỗi client có scope tối thiểu (product:read, license:read, order:write) và có thể giới hạn theo IP/CIDR. Secret chỉ hiển thị một lần.

Create one in Admin → API Clients. Each client has minimal scopes (product:read, license:read, order:write) and can be restricted by IP/CIDR. The secret is shown once.

Reseller API key

Reseller API key

Đại lý tạo key mbr_… trong Reseller Portal → API keys. Key chỉ hiển thị một lần; giới hạn 120 yêu cầu/phút cho mỗi key.

Resellers create mbr_… keys in the Reseller Portal → API keys. A key is shown once; the limit is 120 requests per minute per key.

Chữ ký yêu cầu v2Request Signature v2

Mọi yêu cầu runtime phải được ký HMAC-SHA256. Chữ ký ràng buộc route, sản phẩm, site, bản cài đặt, phiên bản, thời điểm và nonce.Every runtime request must be signed with HMAC-SHA256. The signature binds route, product, site, installation, version, time and nonce.

Chuỗi chuẩn hoá (canonical string)

Canonical string

Nối 10 trường sau bằng ký tự xuống dòng \n (không có xuống dòng ở cuối):

Join these 10 fields with a newline \n (no trailing newline):

Tất cả trường được cắt khoảng trắng đầu/cuối trước khi nối.

All fields are trimmed of leading and trailing whitespace before joining.

Khoá HMAC & kết quả

HMAC key & output

• activate và transfer_claim: khoá là license key đã chuẩn hoá — viết hoa và chỉ giữ A–Z, 0–9, -.
• check, heartbeat, update, deactivate: khoá là lease token nguyên bản.
• Kết quả là chuỗi hex 64 ký tự (chữ thường) gửi trong request_signature, kèm signature_version: 2.

• activate and transfer_claim: the key is the normalized license key — upper-cased, keeping only A–Z, 0–9, -.
• check, heartbeat, update, deactivate: the key is the lease token, verbatim.
• The output is a 64-character lower-case hex string sent as request_signature, with signature_version: 2.

Chuẩn hoá site_url

Normalizing site_url

Máy chủ chuẩn hoá site_url trước khi kiểm tra chữ ký, nên bạn phải ký đúng dạng đã chuẩn hoá:

The server normalizes site_url before verifying the signature, so you must sign the normalized form:

• Scheme phải là http hoặc https; không có user/password.
• Host viết thường, bỏ dấu chấm cuối, bỏ tiền tố www..
• Giữ nguyên cổng nếu có; bỏ dấu / ở cuối đường dẫn; bỏ query và fragment.

• Scheme must be http or https; no user info.
• Host is lower-cased, loses a trailing dot and a leading www..
• An explicit port is kept; trailing / is removed from the path; query and fragment are dropped.

https://WWW.Example.com/        →  https://example.com
https://shop.example.com:8443/  →  https://shop.example.com:8443
https://example.com/blog/       →  https://example.com/blog

Thời gian & chống phát lại

Time & replay protection

request_ts phải lệch giờ máy chủ tối đa REQUEST_SKEW (mặc định 5 phút); hãy đồng bộ NTP. Mỗi request_nonce chỉ dùng được một lần trong NONCE_TTL (mặc định 10 phút) cho mỗi (khoá, route); dùng lại sẽ nhận 409 signature_replay. Sinh nonce mới cho mỗi lần gọi, kể cả khi thử lại.

request_ts must be within REQUEST_SKEW of server time (default 5 minutes), so keep clocks on NTP. Each request_nonce can be used once per (key, route) within NONCE_TTL (default 10 minutes); reuse returns 409 signature_replay. Generate a fresh nonce for every call, retries included.

Vector kiểm thử

Test vector

Dùng để kiểm tra bản cài đặt của bạn. Khoá (secret) ở đây là một chuỗi ASCII 32 ký tự.

Use it to check your implementation. The secret here is a 32-character ASCII string.

secret    = 01234567890123456789012345678901
canonical = "activate\ndemo\nhttps://example.com\ninst\n1.0.0\n1700000000\nnonce-123\nproduction\nstable\nMBT-test"
signature = HMAC_SHA256_hex(secret, canonical)

Các endpoint runtimeRuntime endpoints

Sáu endpoint POST dùng chung một dạng body; chỉ khác route, thông tin xác thực và vài trường tuỳ chọn.Six POST endpoints share one body shape; they differ in route, credential and a few optional fields.

Body yêu cầu

Request body

Danh sách endpoint

Endpoint list

activate

Kích hoạt license cho một site/bản cài đặt và cấp lease. Gọi lại với cùng instance_id là idempotent về mặt kích hoạt. Vượt max_activations sẽ bị từ chối.

Activates a license for a site/installation and issues a lease. Repeating the call with the same instance_id does not consume another activation. Exceeding max_activations is rejected.

check

Kiểm tra lease còn hợp lệ và trả trạng thái license, entitlement, policy hiện tại. Dùng khi khởi động và trước khi mở tính năng trả phí.

Validates the lease and returns the current license status, entitlements and policy. Use it at start-up and before unlocking paid features.

heartbeat

Báo cáo bản cài đặt còn hoạt động và tự gia hạn lease khi cần. Gọi định kỳ (ví dụ mỗi 12 giờ) — dưới LEASE_TTL.

Reports that the installation is alive and renews the lease when needed. Call it periodically (e.g. every 12 h) — shorter than LEASE_TTL.

deactivate

Giải phóng lượt kích hoạt và thu hồi lease của bản cài đặt hiện tại. Sau khi thành công hãy xoá lease token đã lưu.

Frees the activation and revokes the current installation's lease. After success, delete the stored lease token.

update

Trả manifest cập nhật có chữ ký; xem trang Cập nhật & tải gói.

Returns a signed update manifest; see Updates & downloads.

transfer/claim

Kích hoạt trên thiết bị đích bằng mã chuyển một lần do quản trị viên/khách tạo. Route dùng khi ký là transfer_claim, khoá là license key, và transfer_token nằm trong chuỗi chuẩn hoá.

Activates the destination device using a one-time transfer code created by an admin or the customer. The route used when signing is transfer_claim, the key is the license key, and transfer_token is part of the canonical string.

Ví dụ: check bằng lease

Example: check with a lease

async function call(route, lease, extra = {}) {
  const f = { product: 'content-studio-pro', site_url: 'https://example.com',
              instance_id: '0fd4c1a2e7b94d6f', app_version: '4.2.0',
              environment: 'production', channel: 'stable', ...extra };
  const ts = Math.floor(Date.now() / 1000);
  const nonce = crypto.randomBytes(16).toString('hex');
  const canonical = [route, f.product, f.site_url, f.instance_id, f.app_version,
                     String(ts), nonce, f.environment, f.channel, f.transfer_token || ''].join('\n');
  const sig = crypto.createHmac('sha256', lease).update(canonical).digest('hex');
  const r = await fetch(`${BASE}/api/v2/${route}`, {
    method: 'POST', headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ ...f, lease_token: lease, request_ts: ts,
      request_nonce: nonce, signature_version: 2, request_signature: sig }),
  });
  return r.json();
}
const state = await call('check', leaseToken);
if (!state.valid) lockPaidFeatures();

TS=$(date +%s); NONCE=$(openssl rand -hex 16); LEASE='mbl_…'
CANON=$(printf 'check\ncontent-studio-pro\nhttps://example.com\n0fd4c1a2e7b94d6f\n4.2.0\n%s\n%s\nproduction\nstable\n' "$TS" "$NONCE")
SIG=$(printf '%s' "$CANON" | openssl dgst -sha256 -hmac "$LEASE" -hex | sed 's/^.* //')
curl -sS https://license.example.com/api/v2/check -H 'Content-Type: application/json' -d "{
  \"lease_token\":\"$LEASE\",\"product\":\"content-studio-pro\",
  \"site_url\":\"https://example.com\",\"instance_id\":\"0fd4c1a2e7b94d6f\",
  \"app_version\":\"4.2.0\",\"environment\":\"production\",\"channel\":\"stable\",
  \"request_ts\":$TS,\"request_nonce\":\"$NONCE\",
  \"signature_version\":2,\"request_signature\":\"$SIG\"}"

Cập nhật & tải góiUpdates & downloads

Phân phối bản phát hành riêng tư với SHA-256, chữ ký Ed25519 và URL tải dùng một lần.Distribute private releases with SHA-256, Ed25519 signatures and single-use download URLs.

Luồng cập nhật

Update flow

1. Gọi POST /api/v2/update (ký bằng lease, có thể gửi channel).
2. Nếu update_available là true, phản hồi có manifest ký và download_url mới.
3. Xác minh chữ ký manifest bằng khoá công khai Ed25519.
4. Tải download_url (GET /api/download/{token}) — chỉ dùng được một lần, hết hạn nhanh.
5. Tính SHA-256 của file và so với package_sha256 trước khi cài.

1. Call POST /api/v2/update (signed with the lease; optionally send channel).
2. If update_available is true, the response carries a signed manifest and a fresh download_url.
3. Verify the manifest signature with the Ed25519 public key.
4. Fetch download_url (GET /api/download/{token}) — single use, short-lived.
5. Compute the file's SHA-256 and compare with package_sha256 before installing.

Phản hồi

Response

Xác minh manifest

Verifying the manifest

Khoá công khai (RELEASE_SIGNING_PUBLIC_KEY_B64) được nhúng sẵn vào sản phẩm. Manifest có các trường product, version, channel, sha256, size, min_wp, min_php, published_at, key_id; sau khi kiểm chữ ký, hãy đối chiếu product, version, channel, sha256 và size với phần còn lại của phản hồi.

The public key (RELEASE_SIGNING_PUBLIC_KEY_B64) is embedded in your product. The manifest holds product, version, channel, sha256, size, min_wp, min_php, published_at, key_id; after checking the signature, cross-check product, version, channel, sha256 and size against the rest of the response.

const crypto = require('crypto');

function verifyManifest(resp, publicKeyB64, expectedProduct) {
  const message = Buffer.from(resp.signed_manifest, 'base64');
  const signature = Buffer.from(resp.manifest_signature, 'base64');
  // Wrap the raw 32-byte Ed25519 key in an SPKI header
  const spki = Buffer.concat([
    Buffer.from('302a300506032b6570032100', 'hex'),
    Buffer.from(publicKeyB64, 'base64'),
  ]);
  const key = crypto.createPublicKey({ key: spki, format: 'der', type: 'spki' });
  if (!crypto.verify(null, message, key, signature)) return false;
  const m = JSON.parse(message.toString('utf8'));
  return m.product === expectedProduct && m.version === resp.latest_version
      && m.sha256.toLowerCase() === resp.package_sha256.toLowerCase()
      && m.size === resp.package_size;
}

Integration API

Cho backend của bạn (cổng thanh toán, CRM, cửa hàng) đọc danh mục sản phẩm, license và ghi nhận đơn hàng.For your backend (payment gateway, CRM, storefront) to read the catalog and licenses and to record orders.

Xác thực

Authentication

Gửi hai header trên mọi yêu cầu. Thiếu scope hoặc sai IP/CIDR sẽ bị từ chối; đăng nhập sai nhiều lần bị giới hạn tốc độ.

Send two headers on every request. A missing scope or a non-allowlisted IP/CIDR is rejected; repeated bad credentials are rate limited.

X-MB-Client: your-client-id
X-MB-Secret: your-client-secret

Liệt kê sản phẩm

List products

curl -s https://license.example.com/api/integration/v1/products \
  -H "X-MB-Client: $CLIENT_ID" -H "X-MB-Secret: $CLIENT_SECRET"

# {"ok":true,"products":[{"id":1,"name":"Content Studio Pro","slug":"content-studio-pro",
#   "status":"active","current_version":"4.3.0"}],"server_time":"…"}

Liệt kê license

List licenses

limit mặc định 50, tối đa 100; kết quả mới nhất trước. License key đầy đủ không bao giờ được trả — chỉ có key_hint.

limit defaults to 50, max 100; newest first. The full license key is never returned — only a key_hint.

{
  "ok": true,
  "licenses": [
    { "id": 12, "key_hint": "…A1B2", "plan": "pro", "status": "active",
      "customer_id": 3, "organization_id": 0, "expires_at": "2027-11-12T00:00:00Z",
      "max_activations": 1, "product": "content-studio-pro" }
  ],
  "server_time": "2026-11-12T08:00:00Z"
}

Tạo / cập nhật đơn hàng

Create / update an order

curl -sS -X POST https://license.example.com/api/integration/v1/orders \
  -H "X-MB-Client: $CLIENT_ID" -H "X-MB-Secret: $CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"provider":"stripe","external_order_id":"ord_1042","license_id":12,
       "product_id":1,"status":"active","amount_minor":199000,"currency":"vnd",
       "renewal_at":"2027-11-12T00:00:00Z"}'

# 201 {"ok":true,"order":{"id":57}}

Body tối đa 64 KiB. Lỗi trả về dạng ngắn gọn, ví dụ invalid_json, invalid_order.

Body is capped at 64 KiB. Errors are short codes such as invalid_json and invalid_order.

Reseller API

Đại lý cấp license trực tiếp từ hệ thống bán hàng của mình, trừ vào quota đã được cấp.Resellers issue licenses straight from their own storefront, drawing down their assigned quota.

Xác thực & giới hạn

Authentication & limits

Authorization: Bearer mbr_YOUR_KEY

Giới hạn 120 yêu cầu/phút cho mỗi key; vượt quá nhận 429 rate_limited. Key sai hoặc đại lý bị khoá nhận 401 api_key_invalid.

The limit is 120 requests per minute per key; beyond it you get 429 rate_limited. A wrong key or a suspended reseller gets 401 api_key_invalid.

Xem quota còn lại

Remaining quota

curl -s https://license.example.com/api/v2/reseller/quota \
  -H "Authorization: Bearer mbr_YOUR_KEY"

# {"ok":true,"quotas":[{"product":"content-studio-pro","name":"Content Studio Pro",
#   "total":100,"used":37,"remaining":63,"expires_at":"2027-06-30T00:00:00Z"}]}

Cấp license

Issue a license

curl -sS -X POST https://license.example.com/api/v2/reseller/licenses \
  -H "Authorization: Bearer mbr_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product":"content-studio-pro","customer_name":"Nguyen Van A",
       "customer_email":"a@example.com","duration":"12m","max_activations":1}'

const r = await fetch('https://license.example.com/api/v2/reseller/licenses', {
  method: 'POST',
  headers: { Authorization: 'Bearer ' + process.env.MBR_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({ product: 'content-studio-pro', customer_name: 'Nguyen Van A',
                         customer_email: 'a@example.com', duration: '12m', max_activations: 1 }),
});
const out = await r.json();
if (r.status === 201) console.log(out.license_key, out.quota_remaining);

<?php
$ch = curl_init('https://license.example.com/api/v2/reseller/licenses');
curl_setopt_array($ch, [
  CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('MBR_KEY'), 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode([
    'product' => 'content-studio-pro', 'customer_name' => 'Nguyen Van A',
    'customer_email' => 'a@example.com', 'duration' => '12m', 'max_activations' => 1,
  ]),
]);
$out = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);

{
  "ok": true,
  "license_id": 88,
  "license_key": "MB-XXXX-XXXX-XXXX-XXXX",
  "product": "content-studio-pro",
  "expires_at": "2027-11-12T08:00:00Z",
  "quota_remaining": 62
}

Lỗi & giới hạn tốc độErrors & rate limits

Cách đọc lỗi và cách xử lý từng loại.How to read errors and how to react to each kind.

Dạng lỗi

Error shape

{ "ok": false, "error": "signature_invalid", "message": "Request signature is invalid." }

Hãy dựa vào error (ổn định, dành cho máy) thay vì message (dành cho người đọc, có thể đổi).

Branch on error (stable, machine-readable), not on message (human text that may change).

Mã lỗi thường gặp

Common error codes

Danh sách trên là các mã đã xác nhận trong mã nguồn; trạng thái license (hết hạn, bị thu hồi, vượt số lần kích hoạt…) được báo qua valid, status và message trong phản hồi.

These are the codes confirmed in the source; license states (expired, revoked, activation limit reached…) are reported through valid, status and message in the response.

Giới hạn tốc độ

Rate limits

SDK WordPress (PHP)WordPress SDK (PHP)

Nếu sản phẩm là plugin WordPress, dùng SDK có sẵn thay vì tự ký yêu cầu.If your product is a WordPress plugin, use the bundled SDK instead of signing requests yourself.

File: sdk/php/class-mblc-wordpress-license-client.php. SDK xử lý lưu lease, Signature v2, chế độ offline grace, circuit breaker, heartbeat nền, manifest cập nhật có chữ ký và kiểm SHA-256 gói.

File: sdk/php/class-mblc-wordpress-license-client.php. The SDK handles lease persistence, Signature v2, offline grace, a circuit breaker, background heartbeat, signed update manifests and package SHA-256 verification.

Cài đặt

Setup

<?php
require_once __DIR__ . '/class-mblc-wordpress-license-client.php';

$client = new MBLC_WordPress_License_Client([
    'server_url'         => 'https://license.example.com',
    'api_base'           => '/api/v2',
    'product'            => 'my-plugin-pro',
    'plugin_file'        => plugin_basename(__FILE__),
    'version'            => MY_PLUGIN_VERSION,
    'license_key'        => get_option('my_plugin_license_key', ''),
    'channel'            => 'stable',
    'release_public_key' => 'BASE64_ED25519_PUBLIC_KEY',
    'strict_signing'     => true,
]);

$client->register_updater();

Sử dụng

Usage

$result = $client->activate();     // after the user submits a license key
if (is_wp_error($result) || empty($result['valid'])) { /* show message */ }

$state = $client->check();         // uses the stored lease automatically
$client->heartbeat();
$client->deactivate();             // also clears the stored lease

• strict_signing yêu cầu xác minh được chữ ký manifest; để true trên môi trường thật.
• SDK mặc định đòi máy chủ dùng HTTPS (trừ localhost, *.local, *.test).
• Khi lease thiếu hoặc lỗi mạng, SDK có thể dùng trạng thái đã lưu cho tới hết thời gian ân hạn.

• strict_signing requires the manifest signature to verify; keep it true in production.
• By default the SDK insists on an HTTPS server (except localhost, *.local, *.test).
• On a missing lease or network failure the SDK may serve the stored state until the grace window ends.

Ngôn ngữ khác

Other languages

Chưa có SDK chính thức cho ngôn ngữ khác. Hãy làm theo Chữ ký yêu cầu v2: chỉ cần HMAC-SHA256, bộ sinh số ngẫu nhiên an toàn và (cho cập nhật) xác minh Ed25519 cùng SHA-256.

There is no official SDK for other languages yet. Follow Request Signature v2: you only need HMAC-SHA256, a secure random generator and (for updates) Ed25519 verification plus SHA-256.

Danh sách trước khi chạy thậtGo-live checklist

Rà soát nhanh trước khi phát hành tích hợp cho khách hàng.A quick review before you ship your integration to customers.

Phía sản phẩm (client)

Product side (client)

• Ký mọi yêu cầu bằng Signature v2; nonce mới cho mỗi lần gọi, kể cả khi thử lại.
• Ký site_url ở dạng đã chuẩn hoá.
• Đồng bộ giờ hệ thống (NTP); lệch quá 5 phút sẽ bị từ chối.
• Chỉ gửi license key lúc activate/transfer, sau đó chỉ dùng lease token.
• Lưu lease token ở nơi an toàn (không log, không gửi telemetry).
• heartbeat định kỳ ngắn hơn LEASE_TTL; hỗ trợ ân hạn offline và khoá tính năng trả phí khi hết ân hạn.
• Xác minh chữ ký manifest Ed25519 và SHA-256 trước khi cài bản cập nhật.
• Dùng HTTPS, kiểm chứng chứng chỉ; backoff luỹ thừa khi nhận 429/5xx.

• Sign every request with Signature v2; use a fresh nonce per call, retries included.
• Sign the normalized site_url.
• Keep the system clock on NTP; more than 5 minutes of skew is rejected.
• Send the license key only for activate/transfer; use the lease token afterwards.
• Store the lease token securely (no logs, no telemetry).
• Run heartbeat more often than LEASE_TTL; support offline grace and lock paid features when it ends.
• Verify the Ed25519 manifest signature and SHA-256 before installing an update.
• Use HTTPS with certificate validation; back off exponentially on 429/5xx.

Phía máy chủ (backend)

Server side (backend)

• Giữ API client secret và mbr_ key trong secret manager; cấp scope tối thiểu và giới hạn IP/CIDR.
• Xoay secret khi nhân sự thay đổi hoặc nghi ngờ lộ.
• Dùng external_order_id để thao tác đơn hàng idempotent.
• Với Reseller API: kiểm tra quota_remaining và đừng thử lại mù quáng yêu cầu cấp license.
• Cấu hình TRUSTED_PROXIES đúng khi chạy sau reverse proxy.

• Keep API client secrets and mbr_ keys in a secret manager; grant minimal scopes and restrict by IP/CIDR.
• Rotate secrets on staff changes or suspected leaks.
• Use external_order_id to make order writes idempotent.
• For the Reseller API: watch quota_remaining and never blindly retry an issue request.
• Set TRUSTED_PROXIES correctly when running behind a reverse proxy.

Vận hành

Operations

Xem thêm docs/PRODUCTION-CHECKLIST.md, docs/SECURITY.md và docs/DEPLOY-DOCKER-VI.md trong repository.

See also docs/PRODUCTION-CHECKLIST.md, docs/SECURITY.md and docs/DEPLOY-DOCKER-VI.md in the repository.