密码与封禁

本页介绍业务服务端如何设置用户的密码，以及封禁和解封用户。

设置密码：密码是可选的。本服务不保存用户的手机号和邮箱，也不提供找回密码；用户忘记密码时，由你的业务系统验证身份后调用设置密码重置。
封禁：用户的所有设备立即下线，不能再登录，数据保留，可以永久封禁，也可以指定时长、到期自动解封。
只想禁止用户发消息、不影响登录和收消息的，使用全局禁言；要彻底移除用户的，使用删除用户。

设置密码

设置或重置用户的密码，没有密码的用户设置后也可以用密码登录。设置后：

该用户的所有设备立即下线，在线的设备会被断开连接并收到密码已修改的通知，需要用新密码重新登录；
这些设备登记的推送令牌随登录一起解绑，不再收到推送，重新登录后由 App 重新登记，见离线推送；
此前签发、尚未使用的登录凭证作废。

每次调用都会让当时登录的全部设备下线。请求超时后重试，也会让两次调用之间新登录的设备下线。

用户本人也可以在客户端修改密码，但需要提供当前密码；没有设置过密码的用户不能在客户端设置密码，只能由服务端设置。

PUT/{org_name}/{app_name}/users/{username}/password

路径参数

org_name、app_name 见接入概述。

参数	类型	说明
`username`	String	用户名

请求体

字段	类型	必填	说明
`password`	String	是	新密码，1 到 64 个字符，不限制复杂度，原样保存（不去除首尾空格）

请求示例

bash

curl -X PUT "$IM_API/$ORG/$APP/users/zhangsan/password" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "password": "N3wPassw0rd"
  }'

响应

成功返回 204 No Content，没有响应体。

错误

HTTP 状态码	`code`	说明
400	`invalid_argument`	密码为空或超过 64 个字符
404	`not_found`	用户不存在或已删除
429	`rate_limited`	超出了应用计算密码哈希的额度（每个应用每秒 100 次，与带密码创建用户共用），按 `Retry-After` 稍后重试

封禁用户

封禁用户后：

该用户的所有设备立即下线，在线的设备会被断开连接并收到账号已被封禁的通知；各设备登记的推送令牌随登录一起解绑，封禁期间不会收到离线推送，他的推送设置和会话免打扰保留；
用户不能再登录：密码正确或登录凭证有效时，登录返回 403 user_disabled，客户端可以据此提示“账号已被封禁”；不能为他签发登录凭证，此前签发的凭证作废；
用户的数据保留：好友关系和群成员身份不变，其他用户仍能看到他的资料，发给他的消息照常保存，解封并重新登录后可以收到；
业务服务端仍可以修改他的资料、设置密码、设置全局禁言，这些操作不改变封禁状态；
封禁的用户仍计入应用的用户数。

限时封禁：传 duration_seconds 时，到期后约 1 分钟内自动解封。省略时为永久封禁，直到调用解封用户。

再次封禁：对已封禁的用户再次调用时，按本次的参数整体覆盖封禁原因和到期时间：省略 reason 会清空原因，省略 duration_seconds 会改为永久封禁，限时封禁从本次调用时重新计算到期时间。请求超时后重试时，请带上与第一次相同的参数。用户被平台封禁时，再次封禁不做任何改变，见平台封禁。

应用处于只读状态时仍可以封禁，便于处置违规用户。

内容安全的处罚：内容安全的自动处罚，以及你的审核人员确认违规时选择的封禁，都以你的应用的身份封禁用户，效果与调用本接口相同：disabled_by 为 tenant，自动处罚的 status_reason 形如“内容安全：自动处罚（24 小时内违规 3 次）”，可以照常解封。平台审核作出的封禁属于平台封禁。

POST/{org_name}/{app_name}/users/{username}/disable

路径参数

org_name、app_name 见接入概述。

参数	类型	说明
`username`	String	用户名

请求体

请求体可以省略，省略时为永久封禁、不填原因。

字段	类型	必填	说明
`reason`	String	否	封禁原因，最长 256 个字符，不能包含控制字符。保存在用户对象的 `status_reason` 中，供你自己查看，不会返回给被封禁的用户
`duration_seconds`	Number	否	封禁时长，单位为秒，1 到 315360000（10 年）。省略表示永久封禁

请求示例

封禁 1 天：

bash

curl -X POST "$IM_API/$ORG/$APP/users/lisi/disable" \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "发布违规内容",
    "duration_seconds": 86400
  }'

响应

成功返回 200 OK，响应体为封禁后的用户对象，status 为 disabled，disabled_by 为 tenant，disabled_until 为到期时间。

json

{
  "username": "lisi",
  "nickname": "",
  "avatar_url": "",
  "attributes": {},
  "status": "disabled",
  "status_reason": "发布违规内容",
  "disabled_by": "tenant",
  "disabled_until": "2026-10-03T19:08:44.477Z",
  "has_password": true,
  "created_via": "openapi",
  "created_at": "2026-10-02T19:05:46.203Z",
  "last_login_at": "2026-10-02T19:08:44.402Z",
  "version": 5
}

错误

HTTP 状态码	`code`	说明
400	`invalid_argument`	`duration_seconds` 不在 1 到 315360000 之间；`reason` 超过 256 个字符或包含控制字符
404	`not_found`	用户不存在或已删除

解封用户

解除封禁，恢复用户的登录能力。封禁时用户的登录已全部失效，解封后需要重新登录。

对没有封禁的用户调用时，直接返回当前的用户信息，可以放心重试。被平台封禁的用户不能由你解封，返回 403 permission_denied。

POST/{org_name}/{app_name}/users/{username}/enable

路径参数

org_name、app_name 见接入概述。

参数	类型	说明
`username`	String	用户名

请求示例

bash

curl -X POST "$IM_API/$ORG/$APP/users/lisi/enable" \
  -H "Authorization: Bearer $APP_TOKEN"

响应

成功返回 200 OK，响应体为解封后的用户对象。

json

{
  "username": "lisi",
  "nickname": "",
  "avatar_url": "",
  "attributes": {},
  "status": "active",
  "status_reason": null,
  "disabled_by": null,
  "disabled_until": null,
  "has_password": true,
  "created_via": "openapi",
  "created_at": "2026-10-02T19:05:46.203Z",
  "last_login_at": "2026-10-02T19:08:44.402Z",
  "version": 7
}

错误

HTTP 状态码	`code`	说明
403	`permission_denied`	该用户被平台封禁，只能由平台解封
404	`not_found`	用户不存在或已删除

平台封禁

平台在处理违法违规内容时（包括平台审核人员处理内容安全的审核记录时）可能封禁你的用户，这时用户对象的 disabled_by 为 platform，status_reason 为平台填写的原因。平台也可以把你封禁的用户改为平台封禁。被平台封禁的用户与你封禁的用户一样不能登录，但你不能撤销平台的处置：

操作	结果
封禁用户	不做任何改变，返回 `200` 和当前的用户信息，`disabled_by` 仍为 `platform`
解封用户	`403 permission_denied`
删除用户	`403 permission_denied`，防止删除后用同一个用户名重新创建来绕开封禁
修改资料、设置密码、全局禁言、踢掉设备	照常执行
以他的身份发送消息	`403 user_disabled`，`details.disabled_by` 为 `platform`。你封禁的用户不受这个限制，业务服务端仍可以用他的身份发送

平台的限时封禁同样会到期自动解封。用户要求注销账号而被平台封禁时，请联系平台处理。

密码与封禁 ​

设置密码 ​

路径参数 ​

请求体 ​

请求示例 ​

响应 ​

错误 ​

封禁用户 ​

路径参数 ​

请求体 ​

请求示例 ​

响应 ​

错误 ​

解封用户 ​

路径参数 ​

请求示例 ​

响应 ​

错误 ​

平台封禁 ​

密码与封禁

设置密码

路径参数

请求体

请求示例

响应

错误

封禁用户

路径参数

请求体

请求示例

响应

错误

解封用户

路径参数

请求示例

响应

错误

平台封禁