Authentication

WuKongIM identifies users by UID, platform classes by device_flag, and concrete endpoints by device_id. Product accounts, login credentials, and permissions remain owned by your product service.

Identity fields

Field	Recommendation
`uid`	Use a stable, non-recycled product user identifier, never a display name
`device_flag`	Represent an App, Web, or other platform class consistently
`device_id`	Represent a concrete installation or endpoint; define reinstall behavior
`token`	Use high entropy, short lifetimes, and protected delivery
`device_level`	Define master/slave policy server-side; do not let clients self-promote

Current v3 Beta behavior

POST /user/token accepts this compatible request and passes device-token metadata to the user use case for storage:

{
  "uid": "u1001",
  "token": "replace-with-a-random-secret",
  "device_flag": 0,
  "device_level": 1
}

Successful response:

{"status": 200}

The default connection verifies this token

gateway.token_auth_on defaults to true, and the current app composition injects the stored device-token verifier. A later CONNECT for the same UID and device_flag must carry the exact token; an empty token, missing device record, or mismatch returns ReasonAuthFail. Set it to false only for a controlled compatibility migration.

The Gateway still:

requires WKProto connections to begin with CONNECT;
stores the UID, device identity, and negotiated protocol version;
negotiates session encryption material by default;
activates the online route after connection success.

Session encryption protects protocol payloads, but it does not replace product authentication, TLS ingress governance, or HTTP API access control.

Recommended production flow

Only trusted product services may access user-token management routes. Add end-to-end rejection tests before production release.

Revocation and logout

POST /user/device_quit clears the stored token for the selected device class and schedules matching owner-local sessions for closure:

{
  "uid": "u1001",
  "device_flag": 0
}

With default token verification enabled, clearing the durable token makes a later CONNECT fail and also closes matching existing sessions. Production should still prove closure and reconnect rejection and synchronize revocation, rotation, and audit state with the product identity system.

HTTP boundary

Current product HTTP routes provide browser-compatible CORS handling but no general product-authentication middleware. A production environment should at least:

expose product APIs only through a private network or service mesh;
authenticate service identity at an API Gateway or reverse proxy;
separate permissions for token, message-send, and membership mutations;
audit caller, request ID, and result without logging plaintext tokens;
rate-limit credential routes and require TLS.

After tightening identity boundaries, continue with Messaging.