服务端 API

强制用户下线

使用 强制用户下线 从可信后端调用 OpenIM 认证 REST 接口。强制指定用户从某个终端退出登录，客户端 SDK 会收到被踢下线回调。请先在接入准备中配置 API 地址；管理员 Token 只能保存在可信后端服务中，不能下发到客户端或写入前端代码。

HTTP 请求

POST {API_ADDRESS}/auth/force_logout

请求示例

curl --request POST "${API_ADDRESS}/auth/force_logout" \
  --header "Content-Type: application/json; charset=utf-8" \
  --header "operationID: ${OPERATION_ID}" \
  --header "token: ${ADMIN_TOKEN}" \
  --data-raw '{
  "platformID": 2,
  "userID": "user_001"
}'

参数

此接口通过请求头传入链路追踪信息，通过 JSON 请求体传递业务参数。除 router 白名单接口外，管理端接口还需要在请求头中携带 APP 管理员 Token。

请求头

Header	是否必填	类型	说明
operationID	是	string	每次请求的唯一链路追踪 ID，建议由后端生成并写入日志。
token	是	string	APP 管理员 Token；仅保存在可信后端服务中。
Content-Type: application/json	是	string	请求体为 JSON 时必须设置。

请求体

{
  "platformID": 2,
  "userID": "user_001"
}

参数名	是否必填	类型	说明
platformID	是	int	需要踢下线的终端类型，参见用户模块的 `PlatformID`。
userID	是	string	需要强制下线的用户 ID。

响应

请求被 OpenIM 正常处理时通常返回 200 OK。业务是否成功以响应体中的 errCode 为准；errCode === 0 表示成功，非 0 表示业务错误。

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": ""
}

响应参数

参数名	类型	说明
errCode	int	业务错误码，0 表示成功。
errMsg	string	错误简要信息，成功时通常为空。
errDlt	string	错误详细信息，成功时通常为空。

错误

如果请求失败，OpenIM 返回错误对象。更多错误码说明见错误码。

{
  "errCode": 1004,
  "errMsg": "RecordNotFoundError",
  "errDlt": ": [1004]RecordNotFoundError"
}

错误场景	可能原因	处理方式
鉴权失败	`secret` 不正确、`token` 缺失或 Token 已过期。	检查服务端配置，重新获取 APP 管理员 Token。
链路追踪困难	`operationID` 缺失或在大量请求中重复使用。	为每次请求生成独立 `operationID`，并在服务端日志中保留。
参数校验失败	请求体字段类型、必填字段或终端类型不符合接口要求。	对照请求体参数表和限制说明检查字段。

权限和限制

将指定用户在指定终端的 Token 标记为 kicked，并通知网关断开对应连接。
必须使用 APP 管理员 Token 调用。
platformID 和 userID 必填。

HTTP 请求

请求示例

参数

请求头

请求体

响应

响应参数

错误

权限和限制

相关页面