授权流程

SDK Open 的业务请求采用“连接绑定会话”模型。客户端在 Command WS 上提交 API Key，运行时校验后把会话绑定到当前 WebSocket 连接；后续业务请求不需要重复携带 token。

授权步骤

建立 Command WS。
调用 auth.create_session。
运行时返回 session_token、expires_in 和 auth_context。
后续业务方法使用当前连接上的绑定会话。

创建会话

CZUR provider 需要使用开放平台生成的 API Key 接入，params.token 填写该 API Key。示例中的 sk-sq-v1-****42F8 是部分隐藏的 API Key，仅用于说明格式。

本地 mock provider 仅用于本地联调，支持 demo-token-42F8 和 mock-token；这些 mock token 不能用于真实 CZUR provider 接入。

json

{
  "request_id": "req-auth-001",
  "method": "auth.create_session",
  "params": {
    "token": "sk-sq-v1-****42F8"
  },
  "client": {
    "source": "your-app",
    "protocol_version": "2.0.0",
    "trace_id": "trc-auth-001"
  }
}

成功响应包含授权上下文。license_mode 和 entitlement_state 会随 API Key 类型和当前设备激活状态变化：

json

{
  "request_id": "req-auth-001",
  "code": 0,
  "message": "ok",
  "data": {
    "session_token": "session-token-...",
    "expires_in": 7200,
    "auth_context": {
      "is_valid": true,
      "account_type": "svip_plus",
      "license_mode": "offline_api_key",
      "entitlement_state": "offline_unlocked",
      "device_scope": [
        { "vid": 4660, "pid": 22136 }
      ],
      "capabilities": [
        "device.list",
        "device.get",
        "device.open",
        "device.close",
        "video.start",
        "video.stop"
      ]
    }
  },
  "ts": 1710000000
}

查询授权上下文

json

{
  "request_id": "req-auth-ctx-001",
  "method": "auth.get_context",
  "params": {}
}

auth_context.capabilities 决定当前会话可调用的方法，device_scope 决定可访问设备范围。

刷新和销毁会话

auth.refresh_session：刷新当前连接绑定的 session。
auth.destroy_session：销毁当前连接绑定的 session，并释放该连接下的 stream 和已打开设备。

销毁会话：

json

{
  "request_id": "req-auth-destroy-001",
  "method": "auth.destroy_session",
  "params": {}
}

设备激活

当 offline_api_key 或本地固定机器授权需要设备激活时，可使用以下两种方式完成当前机器和会话的授权升级。

方式一：在开放平台控制台根据当前机器码生成离线设备授权码，然后通过 auth.activate_offline 激活当前连接绑定的会话。API 方法名仍为 auth.activate_offline：

json

{
  "request_id": "req-offline-001",
  "method": "auth.activate_offline",
  "params": {
    "auth_code": "CZUR-xxxx"
  }
}

方式二：打开本地 Admin 站点的授权页，找到需要激活的 session，扫描页面二维码完成激活。授权小程序的登录账号和授权数量，请联系成者商务人员获取。

开放平台默认的离线设备授权策略面向体验测试设备：每个开放平台账号最多 2 台不同机器，授权码默认有效 30 天。更多设备、市场或商业化场景，以及授权数量和有效期调整，请联系成者（CZUR）商务人员。

成功后，新的 auth_context.entitlement_state 会反映当前授权状态。

授权流程 ​

授权步骤 ​

创建会话 ​

查询授权上下文 ​

刷新和销毁会话 ​

设备激活 ​

授权流程

授权步骤

创建会话

查询授权上下文

刷新和销毁会话

设备激活