Authorization

SDK Open uses a connection-bound session model. The client submits an API key on Command WS. After validation, the runtime binds a session to the current WebSocket connection, and later business requests do not need to resend the token.

Authorization Steps

1. Open Command WS.
2. Call auth.create_session.
3. Receive session_token, expires_in, and auth_context.
4. Call business methods on the same bound connection.

Create a Session

The CZUR provider requires an API key issued by the Open Platform. Put that API key in params.token. The sk-sq-v1-****42F8 value below is a partially masked API key used only to show the format.

The local mock provider is for local integration testing only. It accepts demo-token-42F8 and mock-token; these mock tokens cannot be used with the real CZUR provider.

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

A successful response includes the auth context. license_mode and entitlement_state vary by API key type and current device activation state:

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

Read the Auth Context

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

auth_context.capabilities determines callable methods. device_scope determines which devices are accessible.

Refresh and Destroy Sessions

• auth.refresh_session: refreshes the session bound to the current connection.
• auth.destroy_session: destroys the bound session and releases streams and opened devices owned by the connection.

Destroy a session:

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

Device Activation

When an offline_api_key or fixed-machine local authorization requires device activation, use either of the following paths to activate the current machine and session.

Option 1: Generate an offline device activation code in the Open Platform console from the current machine code, then activate the session bound to the current connection through auth.activate_offline. The API method name remains auth.activate_offline:

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

Option 2: Open the local Admin site's Authorization page, find the session that requires activation, and scan the QR code shown on the page. Contact CZUR business staff to obtain the authorization mini program login account and activation quota.

The default Open Platform offline device activation policy is for trial/test devices: each Open Platform account can activate at most 2 different machines, and activation codes are valid for 30 days by default. For more devices, market or commercial rollout, or adjusted activation quota and validity, contact CZUR business staff.

After success, the returned auth_context.entitlement_state reflects the current entitlement state.