API 版本相容性與 Client 升級

Platform、SDK、API Revision 是不同東西

何時回 HTTP 426

除 /device/v1/healthz 外，每個 Device API Request 都必須帶 X-Keygen-Device-API-Version: 2026-07-27。Header 缺少時回 CLIENT_API_VERSION_REQUIRED；值不同時回 CLIENT_API_VERSION_UNSUPPORTED。Gateway 會在 Registration、Validation、Heartbeat、Usage 與其他授權業務邏輯之前拒絕。

官方 SDK 自動送出版本 Header

使用 DeviceLicenseClient 時不需要自行建立 Header。若 Server 要求不同 Revision，應安裝管理員提供的目前 SDK Wheel，而不是只改字串。

Python 正確錯誤處理

from keygen_device_sdk import (

    ClientCompatibilityError,

    GatewayError,

    LicenseSDKError,

)



try:

    state = client.ensure_registered(first_key)

    state.require("HDL_EXPORT")

except ClientCompatibilityError as exc:

    disable_protected_features()

    show_upgrade_required(

        current_api=exc.provided_api_version or "missing",

        required_api=exc.required_api_version,

        required_sdk=exc.required_sdk_version,

    )

except GatewayError as exc:

    handle_gateway_error(exc)

except LicenseSDKError as exc:

    handle_license_error(exc)

ClientCompatibilityError 是 GatewayError 的子類別。可讀取 provided_api_version、required_api_version、client_sdk_version、required_sdk_version、platform_version 與 documentation_path。應先捕捉它，再捕捉一般 GatewayError。

自行實作 HTTP Client

官方支援路徑是 Python SDK。自訂 Client 可聲明 Header，但 Header 不是安全憑證，只表示該 Client 已完整實作目前契約。

headers = {

    "Accept": "application/json",

    "X-Keygen-Device-API-Version": "2026-07-27",

    "X-Keygen-SDK-Version": "custom-client/1.0.0",

}

• 實作目前 Request Body 與欄位限制
• 實作 TPM P-256 Challenge／Proof 與 raw r||s 簽章格式
• 驗證 Gateway Ed25519 Signed Envelope、Key ID 與有效時間
• 正確分流 403、426、429、503
• 對 Usage、Component、Process 等狀態變更操作設計冪等與重試邊界

健康檢查用來發現目前契約

GET /device/v1/healthz 不要求 API Header，會回傳 device_api_version、required_client_sdk、Compatibility Policy 與 Platform。它只用於部署與版本發現，不能取代 License validation。

{"status":"ok","device_api":"1","device_api_version":"2026-07-27","api_compatibility_policy":"EXACT","required_client_sdk":"3.1.0","platform":"13.3.7"}

收到 426 後的順序

1. 停止授權操作

   停用受保護功能，不要重送相同舊 Request。

2. 顯示升級訊息

   顯示目前與必要 API Revision、必要 SDK 與 Platform；不要顯示成 License 過期。

3. 安裝目前 SDK

   使用管理員提供且已驗證 SHA-256 的 Wheel。

4. 重新驗收

   跑 Quickstart、Validation、Session、Usage、Heartbeat 與錯誤處理測試。