密碼與封禁

從你的服務端設定使用者密碼，或封禁、解封使用者。處置違規使用者時，按想達到的效果選擇：

要做什麼	用什麼	能登入	能收訊息	能發訊息	資料
只禁止發言	全域性禁言	能	能	不能	保留
暫時或永久禁止使用	封禁使用者	不能，裝置全部下線	解封后補收	不能	保留
徹底移除	刪除使用者	不能	不能	不能	清除
讓使用者重新登入一次	踢掉全部裝置	能，重新登入即可	能	能	保留

例如，封禁 lisi 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 }'

密碼是可選的。本服務不儲存使用者的手機號和郵箱，也不提供找回密碼；使用者忘記密碼時，由你的業務系統驗證身份後呼叫設定密碼重置。

設定密碼

設定或重置使用者的密碼；沒有密碼的使用者設定後也能用密碼登入。

設定後所有裝置都會下線

線上裝置被斷開，收到密碼已修改的通知，要用新密碼重新登入；
裝置登記的推送令牌一起解綁，重新登入後由 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`。你封禁的使用者不受這個限制，業務服務端仍可以用他的身份傳送

平臺的限時封禁同樣會到期自動解封。使用者要求登出賬號而被平臺封禁時，請聯絡平臺處理。

密碼與封禁 ​

設定密碼 ​

路徑引數 ​

請求體 ​

請求示例 ​

響應 ​

錯誤 ​

封禁使用者 ​

路徑引數 ​

請求體 ​

請求示例 ​

響應 ​

錯誤 ​

解封使用者 ​

路徑引數 ​

請求示例 ​

響應 ​

錯誤 ​

平臺封禁 ​

密碼與封禁

設定密碼

路徑引數

請求體

請求示例

響應

錯誤

封禁使用者

路徑引數

請求體

請求示例

響應

錯誤

解封使用者

路徑引數

請求示例

響應

錯誤

平臺封禁