AgentbaseDocs
文档目录

用户 API

用户资源的全生命周期管理接口:创建(明文密码或导入既有密码哈希)、资料与状态维护、标签与偏好、MFA、目标(推送/邮件/短信通道)、OAuth 身份、Session 与 Custom Token 签发。登录认证流(邮箱密码 / OAuth / Magic URL 的客户端换取流程)不在本目录范围,服务端侧只提供本页的管理与签发接口。

资源与基础路径

认证与权限

认证与请求头约定见 通用约定。本域涉及的 scope:

scope覆盖操作
users.read用户/身份/Session/日志/成员关系/MFA 因子读取
users.write创建与修改用户、密码、状态、标签、偏好、MFA 管理、Session 管理、Token/JWT 签发、身份删除
targets.read / targets.write用户 target 资源的读写

端点清单

方法 + 路径用途
GET /users列出用户(分页/搜索)
POST /users创建用户(明文密码)
POST /users/argon2以 Argon2 哈希导入创建用户
POST /users/bcrypt以 Bcrypt 哈希导入创建用户
POST /users/md5以 MD5 哈希导入创建用户
POST /users/phpass以 PHPass 哈希导入创建用户
POST /users/scrypt以 Scrypt 哈希导入创建用户
POST /users/scrypt-modified以 Scrypt Modified 哈希导入创建用户
POST /users/sha以 SHA 哈希导入创建用户
GET /users/{userId}获取单个用户
DELETE /users/{userId}删除用户
PATCH /users/{userId}/email修改邮箱
PATCH /users/{userId}/name修改姓名
PATCH /users/{userId}/password重置密码(明文,服务端重新哈希)
PATCH /users/{userId}/phone修改手机号
PATCH /users/{userId}/status启用/封禁用户
PATCH /users/{userId}/verification直接置位邮箱验证状态
PATCH /users/{userId}/verification/phone直接置位手机验证状态
PUT /users/{userId}/labels整体替换用户标签
PATCH /users/{userId}/impersonator设置/取消用户受限身份(impersonator)能力
GET /users/{userId}/prefs读取用户偏好
PATCH /users/{userId}/prefs合并写入用户偏好
GET /users/{userId}/logs用户活动日志
GET /users/{userId}/memberships用户在团队中的成员关系列表
POST /users/{userId}/tokens签发短时 Custom Token
POST /users/{userId}/jwts为既有 Session 签发 JWT
GET /users/{userId}/sessions列出用户 Session
POST /users/{userId}/sessions为用户创建 Session
DELETE /users/{userId}/sessions吊销全部 Session
DELETE /users/{userId}/sessions/{sessionId}吊销单个 Session
GET /users/{userId}/mfa/factors列出 MFA 因子
PATCH /users/{userId}/mfa开关用户 MFA
DELETE /users/{userId}/mfa/authenticators/{type}删除认证器(type=totp)
GET /users/{userId}/mfa/recovery-codes读取恢复码
PATCH /users/{userId}/mfa/recovery-codes生成恢复码
PUT /users/{userId}/mfa/recovery-codes重新生成恢复码
GET /users/identities列出 OAuth 身份
DELETE /users/identities/{identityId}删除身份
GET /users/{userId}/targets列出消息目标
POST /users/{userId}/targets创建消息目标
GET /users/{userId}/targets/{targetId}获取消息目标
PATCH /users/{userId}/targets/{targetId}更新消息目标
DELETE /users/{userId}/targets/{targetId}删除消息目标

请求与响应

以下按端点逐个给出输入、输出、可复制的调用示例与响应示例。所有示例的 <your-endpoint>、<YOUR_PROJECT_ID>、<YOUR_API_KEY> 替换为你的接入点、项目 ID 与 API Key;POST/PUT/PATCH 示例的请求体为 JSON,字段必填性与默认值以「输入」表为准。

GET /v1/users

列出项目内全部用户,支持按用户属性过滤与模糊搜索。

输入:

参数位置类型必填默认/枚举说明
queriesquerystring[]否默认 []Query 数组(形如 limit(25)、offset(0)、equal("status","true")),最多 100 条、每条最长 4096 字符;可过滤字段:name、email、phone、status、passwordUpdate、registration、emailVerification、phoneVerification、labels、impersonator
searchquerystring否模糊搜索词(最长 256 字符),覆盖姓名与邮箱
totalqueryboolean否默认 true传 false 跳过计数,total 恒返回 0

输出:200,返回 userList 模型:total 为匹配总数,users[] 为用户数组。分页游标取上一页最后一条的 $id 配合 cursorAfter() 使用。

字段类型说明
totalinteger匹配查询的用户总数(total=false 时恒为 0)
users[]user[]用户对象,字段结构见 [POST /v1/users](#post-v1users) 输出说明

调用示例:

curl \
  "https://<your-endpoint>/v1/users?queries[]=limit(25)&queries[]=offset(0)&total=false" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "total": 2,
  "users": [
    {
      "$id": "66a9d8ef00f21",
      "$createdAt": "2020-10-15T06:38:00.000+00:00",
      "$updatedAt": "2020-10-15T06:38:00.000+00:00",
      "name": "Ada Lovelace",
      "password": "$argon2id$v=19$m=2048,t=4,p=3$aUZjLnliVWRINmFNTWMudg$5S+x+7uA31xFnrHFT47yFwcJeaP0w92L/4LdgrVRXxE",
      "hash": "argon2",
      "hashOptions": {
        "type": "argon2",
        "memoryCost": 65536,
        "timeCost": 4,
        "threads": 3
      },
      "registration": "2020-10-15T06:38:00.000+00:00",
      "status": true,
      "labels": [
        "vip"
      ],
      "passwordUpdate": "2020-10-15T06:38:00.000+00:00",
      "email": "ada@example.com",
      "phone": "+12065550100",
      "emailVerification": false,
      "phoneVerification": false,
      "mfa": false,
      "prefs": {
        "theme": "pink",
        "timezone": "UTC"
      },
      "targets": [],
      "accessedAt": "2020-10-15T06:38:00.000+00:00",
      "impersonator": false,
      "impersonatorUserId": null
    },
    {
      "$id": "66a9d8f111b3c",
      "$createdAt": "2020-10-15T06:38:00.000+00:00",
      "$updatedAt": "2020-10-15T06:38:00.000+00:00",
      "name": "Grace Hopper",
      "password": "$argon2id$v=19$m=2048,t=4,p=3$aUZjLnliVWRINmFNTWMudg$5S+x+7uA31xFnrHFT47yFwcJeaP0w92L/4LdgrVRXxE",
      "hash": "argon2",
      "hashOptions": {
        "type": "argon2",
        "memoryCost": 65536,
        "timeCost": 4,
        "threads": 3
      },
      "registration": "2020-10-15T06:38:00.000+00:00",
      "status": true,
      "labels": [],
      "passwordUpdate": "2020-10-15T06:38:00.000+00:00",
      "email": "grace@example.com",
      "phone": "+12065550100",
      "emailVerification": false,
      "phoneVerification": false,
      "mfa": false,
      "prefs": {
        "theme": "pink",
        "timezone": "UTC"
      },
      "targets": [],
      "accessedAt": "2020-10-15T06:38:00.000+00:00",
      "impersonator": false,
      "impersonatorUserId": null
    }
  ]
}

POST /v1/users

创建用户(明文密码由服务端哈希存储)。不传 password 时创建无密码用户,后续可用 [PATCH /v1/users/{userId}/password](#patch-v1usersuseridpassword) 补设。

输入:

参数位置类型必填默认/枚举说明
userIdbodystring是用户 ID:自定义或传 unique() 由服务端生成;可用字符 a-z、A-Z、0-9、.、-、_,不能以特殊字符开头,最长 36 字符
emailbodystring否邮箱;项目内唯一,重复返回 409 user_already_exists
phonebodystring否手机号,+ 开头含国家码(E.164),如 +12065550100
passwordbodystring否明文密码,至少 8 字符;服务端以项目默认算法(Argon2)哈希
namebodystring否姓名,最长 128 字符

输出:201,返回 user 模型。完整字段表:

字段类型说明
$idstring用户 ID
$createdAtstring创建时间(ISO 8601)
$updatedAtstring最近更新时间(ISO 8601)
namestring姓名
passwordstring?哈希后的密码串(管理 API 不回显明文;经哈希导入端点创建时为源系统的哈希)
hashstring?密码哈希算法名(argon2 / bcrypt / md5 / phpass / scrypt / scryptModified / sha)
hashOptionsobject?哈希算法参数(algoArgon2 / algoScrypt 等,结构与 hash 对应;如 Argon2 为 type/memoryCost/timeCost/threads)
registrationstring注册时间(ISO 8601)
statusboolean启用状态:true 启用、false 封禁
labelsstring[]用户标签(label:<name> 权限的判定依据)
passwordUpdatestring最近一次密码更新时间(ISO 8601)
emailstring邮箱(未设置时为空串)
phonestring手机号(E.164 格式,未设置时为空串)
emailVerificationboolean邮箱验证状态
phoneVerificationboolean手机验证状态
mfaboolean是否启用 MFA
prefsobject偏好键值对象
targetstarget[]消息目标列表(同一结构见 targets 端点)
accessedAtstring最近访问时间(ISO 8601,24 小时内不重复刷新)
impersonatorboolean?是否具备受限身份(impersonator)能力
impersonatorUserIdstring?当前请求处于模拟态时的原始执行者用户 ID

调用示例:

curl \
  -X POST \
  "https://<your-endpoint>/v1/users" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "userId": "66a9d8ef00f21",
  "email": "ada@example.com",
  "phone": "+12065550100",
  "password": "s3cret-Passw0rd",
  "name": "Ada Lovelace"
}'

响应示例:

{
  "$id": "66a9d8ef00f21",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "name": "Ada Lovelace",
  "password": "$argon2id$v=19$m=2048,t=4,p=3$aUZjLnliVWRINmFNTWMudg$5S+x+7uA31xFnrHFT47yFwcJeaP0w92L/4LdgrVRXxE",
  "hash": "argon2",
  "hashOptions": {},
  "registration": "2020-10-15T06:38:00.000+00:00",
  "status": true,
  "labels": [
    "vip"
  ],
  "passwordUpdate": "2020-10-15T06:38:00.000+00:00",
  "email": "ada@example.com",
  "phone": "+12065550100",
  "emailVerification": false,
  "phoneVerification": false,
  "mfa": false,
  "prefs": {
    "theme": "pink",
    "timezone": "UTC"
  },
  "targets": [],
  "accessedAt": "2020-10-15T06:38:00.000+00:00",
  "impersonator": false,
  "impersonatorUserId": null
}

创建密码已知的最终用户应改用客户端注册流;本端点面向服务端管理场景(如管理员代建账号、同步外部用户目录)。

POST /v1/users/argon2

以 Argon2 哈希导入创建用户:password 传入源系统中的 Argon2 哈希串,服务端不再哈希,登录时直接按 Argon2 校验。适用于把既有用户体系无缝迁移到本平台。

输入:

参数位置类型必填默认/枚举说明
userIdbodystring是同 [POST /v1/users](#post-v1users) 的 userId 约束
emailbodystring是邮箱;项目内唯一
passwordbodystring是源系统的 Argon2 哈希串(如 $argon2id$v=19$m=2048,t=4,p=3$...),服务端原样存储
namebodystring否姓名,最长 128 字符

输出:201,返回 user;hash 字段为 argon2,hashOptions 回显哈希参数。完整字段见 [POST /v1/users](#post-v1users)。

调用示例:

curl \
  -X POST \
  "https://<your-endpoint>/v1/users/argon2" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "userId": "66a9d8ef00f21",
  "email": "ada@example.com",
  "password": "$argon2id$v=19$m=2048,t=4,p=3$aUZjLnliVWRINmFNTWMudg$5S+x+7uA31xFnrHFT47yFwcJeaP0w92L/4LdgrVRXxE",
  "name": "Ada Lovelace"
}'

响应示例:

{
  "$id": "66a9d8ef00f21",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "name": "Ada Lovelace",
  "password": "$argon2id$v=19$m=2048,t=4,p=3$aUZjLnliVWRINmFNTWMudg$5S+x+7uA31xFnrHFT47yFwcJeaP0w92L/4LdgrVRXxE",
  "hash": "argon2",
  "hashOptions": {
    "type": "argon2",
    "memoryCost": 65536,
    "timeCost": 4,
    "threads": 3
  },
  "registration": "2020-10-15T06:38:00.000+00:00",
  "status": true,
  "labels": [
    "vip"
  ],
  "passwordUpdate": "2020-10-15T06:38:00.000+00:00",
  "email": "ada@example.com",
  "phone": "+12065550100",
  "emailVerification": false,
  "phoneVerification": false,
  "mfa": false,
  "prefs": {
    "theme": "pink",
    "timezone": "UTC"
  },
  "targets": [],
  "accessedAt": "2020-10-15T06:38:00.000+00:00",
  "impersonator": false,
  "impersonatorUserId": null
}

POST /v1/users/bcrypt

以 Bcrypt 哈希导入创建用户,语义同 [POST /v1/users/argon2](#post-v1usersargon2)。

输入:

参数位置类型必填默认/枚举说明
userIdbodystring是同 [POST /v1/users](#post-v1users) 的 userId 约束
emailbodystring是邮箱;项目内唯一
passwordbodystring是源系统的 Bcrypt 哈希串(如 $2a$12$...)
namebodystring否姓名,最长 128 字符

输出:201,返回 user;hash 为 bcrypt。完整字段见 [POST /v1/users](#post-v1users)。

调用示例:

curl \
  -X POST \
  "https://<your-endpoint>/v1/users/bcrypt" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "userId": "66a9d8ef00f21",
  "email": "ada@example.com",
  "password": "$2a$12$R9h/cIPz0gi.URNNX3kh2OPST9/PgBkqquzi.Ss7KIUgO2t0jWMUW",
  "name": "Ada Lovelace"
}'

响应示例:

{
  "$id": "66a9d8ef00f21",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "name": "Ada Lovelace",
  "password": "$argon2id$v=19$m=2048,t=4,p=3$aUZjLnliVWRINmFNTWMudg$5S+x+7uA31xFnrHFT47yFwcJeaP0w92L/4LdgrVRXxE",
  "hash": "bcrypt",
  "hashOptions": {
    "type": "argon2",
    "memoryCost": 65536,
    "timeCost": 4,
    "threads": 3
  },
  "registration": "2020-10-15T06:38:00.000+00:00",
  "status": true,
  "labels": [
    "vip"
  ],
  "passwordUpdate": "2020-10-15T06:38:00.000+00:00",
  "email": "ada@example.com",
  "phone": "+12065550100",
  "emailVerification": false,
  "phoneVerification": false,
  "mfa": false,
  "prefs": {
    "theme": "pink",
    "timezone": "UTC"
  },
  "targets": [],
  "accessedAt": "2020-10-15T06:38:00.000+00:00",
  "impersonator": false,
  "impersonatorUserId": null
}

POST /v1/users/md5

以 MD5 哈希导入创建用户,语义同 [POST /v1/users/argon2](#post-v1usersargon2)。MD5 已不安全,导入后建议引导用户重置密码。

输入:

参数位置类型必填默认/枚举说明
userIdbodystring是同 [POST /v1/users](#post-v1users) 的 userId 约束
emailbodystring是邮箱;项目内唯一
passwordbodystring是源系统的 MD5 哈希串(32 位十六进制,如 5f4dcc3b5aa765d61d8327deb882cf99)
namebodystring否姓名,最长 128 字符

输出:201,返回 user;hash 为 md5。完整字段见 [POST /v1/users](#post-v1users)。

调用示例:

curl \
  -X POST \
  "https://<your-endpoint>/v1/users/md5" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "userId": "66a9d8ef00f21",
  "email": "ada@example.com",
  "password": "5f4dcc3b5aa765d61d8327deb882cf99",
  "name": "Ada Lovelace"
}'

响应示例:

{
  "$id": "66a9d8ef00f21",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "name": "Ada Lovelace",
  "password": "$argon2id$v=19$m=2048,t=4,p=3$aUZjLnliVWRINmFNTWMudg$5S+x+7uA31xFnrHFT47yFwcJeaP0w92L/4LdgrVRXxE",
  "hash": "md5",
  "hashOptions": {
    "type": "argon2",
    "memoryCost": 65536,
    "timeCost": 4,
    "threads": 3
  },
  "registration": "2020-10-15T06:38:00.000+00:00",
  "status": true,
  "labels": [
    "vip"
  ],
  "passwordUpdate": "2020-10-15T06:38:00.000+00:00",
  "email": "ada@example.com",
  "phone": "+12065550100",
  "emailVerification": false,
  "phoneVerification": false,
  "mfa": false,
  "prefs": {
    "theme": "pink",
    "timezone": "UTC"
  },
  "targets": [],
  "accessedAt": "2020-10-15T06:38:00.000+00:00",
  "impersonator": false,
  "impersonatorUserId": null
}

POST /v1/users/phpass

以 PHPass 哈希导入创建用户(WordPress 等系统常用),语义同 [POST /v1/users/argon2](#post-v1usersargon2)。

输入:

参数位置类型必填默认/枚举说明
userIdbodystring是同 [POST /v1/users](#post-v1users) 的 userId 约束
emailbodystring是邮箱;项目内唯一
passwordbodystring是源系统的 PHPass 哈希串(如 $P$B...)
namebodystring否姓名,最长 128 字符

输出:201,返回 user;hash 为 phpass。完整字段见 [POST /v1/users](#post-v1users)。

调用示例:

curl \
  -X POST \
  "https://<your-endpoint>/v1/users/phpass" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "userId": "66a9d8ef00f21",
  "email": "ada@example.com",
  "password": "$P$BpB4iZ4sRoQyBfq0PfPOiZyEpX6xj.",
  "name": "Ada Lovelace"
}'

响应示例:

{
  "$id": "66a9d8ef00f21",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "name": "Ada Lovelace",
  "password": "$argon2id$v=19$m=2048,t=4,p=3$aUZjLnliVWRINmFNTWMudg$5S+x+7uA31xFnrHFT47yFwcJeaP0w92L/4LdgrVRXxE",
  "hash": "phpass",
  "hashOptions": {
    "type": "argon2",
    "memoryCost": 65536,
    "timeCost": 4,
    "threads": 3
  },
  "registration": "2020-10-15T06:38:00.000+00:00",
  "status": true,
  "labels": [
    "vip"
  ],
  "passwordUpdate": "2020-10-15T06:38:00.000+00:00",
  "email": "ada@example.com",
  "phone": "+12065550100",
  "emailVerification": false,
  "phoneVerification": false,
  "mfa": false,
  "prefs": {
    "theme": "pink",
    "timezone": "UTC"
  },
  "targets": [],
  "accessedAt": "2020-10-15T06:38:00.000+00:00",
  "impersonator": false,
  "impersonatorUserId": null
}

POST /v1/users/scrypt

以 Scrypt 哈希导入创建用户。Scrypt 校验需要源系统的完整哈希参数,因此除哈希串外必须一并传入 salt 与代价参数。

输入:

参数位置类型必填默认/枚举说明
userIdbodystring是同 [POST /v1/users](#post-v1users) 的 userId 约束
emailbodystring是邮箱;项目内唯一
passwordbodystring是源系统的 Scrypt 哈希串
passwordSaltbodystring是哈希所用 salt
passwordCpubodyinteger是CPU 代价参数(源系统配置)
passwordMemorybodyinteger是内存代价参数(源系统配置)
passwordParallelbodyinteger是并行化参数(源系统配置)
passwordLengthbodyinteger是哈希输出长度(源系统配置)
namebodystring否姓名,最长 128 字符

输出:201,返回 user;hash 为 scrypt,hashOptions 回显以上参数。完整字段见 [POST /v1/users](#post-v1users)。

调用示例:

curl \
  -X POST \
  "https://<your-endpoint>/v1/users/scrypt" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "userId": "66a9d8ef00f21",
  "email": "ada@example.com",
  "password": "6d6c6f5f736372797074",
  "passwordSalt": "b3JpZ2luYWwtc2FsdA==",
  "passwordCpu": 1,
  "passwordMemory": 14,
  "passwordParallel": 8,
  "passwordLength": 32,
  "name": "Ada Lovelace"
}'

响应示例:

{
  "$id": "66a9d8ef00f21",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "name": "Ada Lovelace",
  "password": "$argon2id$v=19$m=2048,t=4,p=3$aUZjLnliVWRINmFNTWMudg$5S+x+7uA31xFnrHFT47yFwcJeaP0w92L/4LdgrVRXxE",
  "hash": "scrypt",
  "hashOptions": {
    "type": "argon2",
    "memoryCost": 65536,
    "timeCost": 4,
    "threads": 3
  },
  "registration": "2020-10-15T06:38:00.000+00:00",
  "status": true,
  "labels": [
    "vip"
  ],
  "passwordUpdate": "2020-10-15T06:38:00.000+00:00",
  "email": "ada@example.com",
  "phone": "+12065550100",
  "emailVerification": false,
  "phoneVerification": false,
  "mfa": false,
  "prefs": {
    "theme": "pink",
    "timezone": "UTC"
  },
  "targets": [],
  "accessedAt": "2020-10-15T06:38:00.000+00:00",
  "impersonator": false,
  "impersonatorUserId": null
}

POST /v1/users/scrypt-modified

以 Scrypt Modified 哈希导入创建用户(Firebase Auth 导出格式),语义同 [POST /v1/users/scrypt](#post-v1usersscrypt),但参数为 Firebase 特有的 salt 分隔符与签名密钥。

输入:

参数位置类型必填默认/枚举说明
userIdbodystring是同 [POST /v1/users](#post-v1users) 的 userId 约束
emailbodystring是邮箱;项目内唯一
passwordbodystring是源系统的 Scrypt Modified 哈希串(base64)
passwordSaltbodystring是哈希所用 salt(base64)
passwordSaltSeparatorbodystring是salt 分隔符(Firebase 导出字段 saltSeparator)
passwordSignerKeybodystring是签名密钥(Firebase 导出字段 signerKey,base64)
namebodystring否姓名,最长 128 字符

输出:201,返回 user;hash 为 scryptModified。完整字段见 [POST /v1/users](#post-v1users)。

调用示例:

curl \
  -X POST \
  "https://<your-endpoint>/v1/users/scrypt-modified" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "userId": "66a9d8ef00f21",
  "email": "ada@example.com",
  "password": "dHJhbnNpZW50LXBhc3N3b3Jk",
  "passwordSalt": "QUJDREVGRw==",
  "passwordSaltSeparator": "c2FsdC1zZXBhcmF0b3I=",
  "passwordSignerKey": "c2lnbmVyLWtleQ==",
  "name": "Ada Lovelace"
}'

响应示例:

{
  "$id": "66a9d8ef00f21",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "name": "Ada Lovelace",
  "password": "$argon2id$v=19$m=2048,t=4,p=3$aUZjLnliVWRINmFNTWMudg$5S+x+7uA31xFnrHFT47yFwcJeaP0w92L/4LdgrVRXxE",
  "hash": "scryptModified",
  "hashOptions": {
    "type": "argon2",
    "memoryCost": 65536,
    "timeCost": 4,
    "threads": 3
  },
  "registration": "2020-10-15T06:38:00.000+00:00",
  "status": true,
  "labels": [
    "vip"
  ],
  "passwordUpdate": "2020-10-15T06:38:00.000+00:00",
  "email": "ada@example.com",
  "phone": "+12065550100",
  "emailVerification": false,
  "phoneVerification": false,
  "mfa": false,
  "prefs": {
    "theme": "pink",
    "timezone": "UTC"
  },
  "targets": [],
  "accessedAt": "2020-10-15T06:38:00.000+00:00",
  "impersonator": false,
  "impersonatorUserId": null
}

POST /v1/users/sha

以 SHA 系列哈希导入创建用户,语义同 [POST /v1/users/argon2](#post-v1usersargon2);用 passwordVersion 指定具体变体。

输入:

参数位置类型必填默认/枚举说明
userIdbodystring是同 [POST /v1/users](#post-v1users) 的 userId 约束
emailbodystring是邮箱;项目内唯一
passwordbodystring是源系统的 SHA 哈希串(十六进制)
passwordVersionbodystring否sha1(默认)/ sha224 / sha256 / sha384 / sha512/224 / sha512/256 / sha512 / sha3-224 / sha3-256 / sha3-384 / sha3-512SHA 变体,需与源系统一致
namebodystring否姓名,最长 128 字符

输出:201,返回 user;hash 为 sha,hashOptions 回显版本。完整字段见 [POST /v1/users](#post-v1users)。

调用示例:

curl \
  -X POST \
  "https://<your-endpoint>/v1/users/sha" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "userId": "66a9d8ef00f21",
  "email": "ada@example.com",
  "password": "8d969eef6ecad3c29a3a629280e686cf0c3f5d5a86aff3ca12020c923adc6c92",
  "passwordVersion": "sha256",
  "name": "Ada Lovelace"
}'

响应示例:

{
  "$id": "66a9d8ef00f21",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "name": "Ada Lovelace",
  "password": "$argon2id$v=19$m=2048,t=4,p=3$aUZjLnliVWRINmFNTWMudg$5S+x+7uA31xFnrHFT47yFwcJeaP0w92L/4LdgrVRXxE",
  "hash": "sha",
  "hashOptions": {
    "type": "argon2",
    "memoryCost": 65536,
    "timeCost": 4,
    "threads": 3
  },
  "registration": "2020-10-15T06:38:00.000+00:00",
  "status": true,
  "labels": [
    "vip"
  ],
  "passwordUpdate": "2020-10-15T06:38:00.000+00:00",
  "email": "ada@example.com",
  "phone": "+12065550100",
  "emailVerification": false,
  "phoneVerification": false,
  "mfa": false,
  "prefs": {
    "theme": "pink",
    "timezone": "UTC"
  },
  "targets": [],
  "accessedAt": "2020-10-15T06:38:00.000+00:00",
  "impersonator": false,
  "impersonatorUserId": null
}

GET /v1/users/{userId}

按 ID 获取单个用户。

输入:

参数位置类型必填默认/枚举说明
userIdpathstring是用户 ID

输出:200,返回 user 模型,完整字段见 [POST /v1/users](#post-v1users)。

调用示例:

curl \
  "https://<your-endpoint>/v1/users/66a9d8ef00f21" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "$id": "66a9d8ef00f21",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "name": "Ada Lovelace",
  "password": "$argon2id$v=19$m=2048,t=4,p=3$aUZjLnliVWRINmFNTWMudg$5S+x+7uA31xFnrHFT47yFwcJeaP0w92L/4LdgrVRXxE",
  "hash": "argon2",
  "hashOptions": {
    "type": "argon2",
    "memoryCost": 65536,
    "timeCost": 4,
    "threads": 3
  },
  "registration": "2020-10-15T06:38:00.000+00:00",
  "status": true,
  "labels": [
    "vip"
  ],
  "passwordUpdate": "2020-10-15T06:38:00.000+00:00",
  "email": "ada@example.com",
  "phone": "+12065550100",
  "emailVerification": false,
  "phoneVerification": false,
  "mfa": false,
  "prefs": {
    "theme": "pink",
    "timezone": "UTC"
  },
  "targets": [],
  "accessedAt": "2020-10-15T06:38:00.000+00:00",
  "impersonator": false,
  "impersonatorUserId": null
}

DELETE /v1/users/{userId}

删除用户。级联删除其全部 Session、OAuth 身份、消息目标与团队成员关系;删除后 ID 可复用,历史日志仍保留原 ID 供审计。

输入:

参数位置类型必填默认/枚举说明
userIdpathstring是用户 ID

输出:204 No Content,无响应体。

调用示例:

curl \
  -X DELETE \
  "https://<your-endpoint>/v1/users/66a9d8ef00f21" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

PATCH /v1/users/{userId}/email

修改用户邮箱。不会自动改写 emailVerification——若需保持验证态有效,请随后调用 [PATCH /v1/users/{userId}/verification](#patch-v1usersuseridverification)。

输入:

参数位置类型必填默认/枚举说明
userIdpathstring是用户 ID
emailbodystring是新邮箱;与其他用户冲突时返回 409 user_already_exists

输出:200,返回 user(关注 email 字段)。完整字段见 [POST /v1/users](#post-v1users)。

字段类型说明
emailstring更新后的邮箱

调用示例:

curl \
  -X PATCH \
  "https://<your-endpoint>/v1/users/66a9d8ef00f21/email" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "ada-new@example.com"
}'

响应示例:

{
  "$id": "66a9d8ef00f21",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "name": "Ada Lovelace",
  "password": "$argon2id$v=19$m=2048,t=4,p=3$aUZjLnliVWRINmFNTWMudg$5S+x+7uA31xFnrHFT47yFwcJeaP0w92L/4LdgrVRXxE",
  "hash": "argon2",
  "hashOptions": {
    "type": "argon2",
    "memoryCost": 65536,
    "timeCost": 4,
    "threads": 3
  },
  "registration": "2020-10-15T06:38:00.000+00:00",
  "status": true,
  "labels": [
    "vip"
  ],
  "passwordUpdate": "2020-10-15T06:38:00.000+00:00",
  "email": "ada-new@example.com",
  "phone": "+12065550100",
  "emailVerification": false,
  "phoneVerification": false,
  "mfa": false,
  "prefs": {
    "theme": "pink",
    "timezone": "UTC"
  },
  "targets": [],
  "accessedAt": "2020-10-15T06:38:00.000+00:00",
  "impersonator": false,
  "impersonatorUserId": null
}

PATCH /v1/users/{userId}/name

修改用户姓名。

输入:

参数位置类型必填默认/枚举说明
userIdpathstring是用户 ID
namebodystring是新姓名,最长 128 字符

输出:200,返回 user(关注 name 字段)。完整字段见 [POST /v1/users](#post-v1users)。

字段类型说明
namestring更新后的姓名

调用示例:

curl \
  -X PATCH \
  "https://<your-endpoint>/v1/users/66a9d8ef00f21/name" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Ada King"
}'

响应示例:

{
  "$id": "66a9d8ef00f21",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "name": "Ada King",
  "password": "$argon2id$v=19$m=2048,t=4,p=3$aUZjLnliVWRINmFNTWMudg$5S+x+7uA31xFnrHFT47yFwcJeaP0w92L/4LdgrVRXxE",
  "hash": "argon2",
  "hashOptions": {
    "type": "argon2",
    "memoryCost": 65536,
    "timeCost": 4,
    "threads": 3
  },
  "registration": "2020-10-15T06:38:00.000+00:00",
  "status": true,
  "labels": [
    "vip"
  ],
  "passwordUpdate": "2020-10-15T06:38:00.000+00:00",
  "email": "ada@example.com",
  "phone": "+12065550100",
  "emailVerification": false,
  "phoneVerification": false,
  "mfa": false,
  "prefs": {
    "theme": "pink",
    "timezone": "UTC"
  },
  "targets": [],
  "accessedAt": "2020-10-15T06:38:00.000+00:00",
  "impersonator": false,
  "impersonatorUserId": null
}

PATCH /v1/users/{userId}/password

重置用户密码(服务端以明文重新哈希)。该用户全部既有 Session 不被自动吊销;如需强制下线,调用 [DELETE /v1/users/{userId}/sessions](#delete-v1usersuseridsessions)。

输入:

参数位置类型必填默认/枚举说明
userIdpathstring是用户 ID
passwordbodystring是新明文密码,至少 8 字符

输出:200,返回 user(关注 passwordUpdate 字段刷新)。完整字段见 [POST /v1/users](#post-v1users)。

字段类型说明
passwordUpdatestring本次重置的时间(ISO 8601)

调用示例:

curl \
  -X PATCH \
  "https://<your-endpoint>/v1/users/66a9d8ef00f21/password" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "password": "n3w-Secret-Pass"
}'

响应示例:

{
  "$id": "66a9d8ef00f21",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "name": "Ada Lovelace",
  "password": "$argon2id$v=19$m=2048,t=4,p=3$aUZjLnliVWRINmFNTWMudg$5S+x+7uA31xFnrHFT47yFwcJeaP0w92L/4LdgrVRXxE",
  "hash": "argon2",
  "hashOptions": {
    "type": "argon2",
    "memoryCost": 65536,
    "timeCost": 4,
    "threads": 3
  },
  "registration": "2020-10-15T06:38:00.000+00:00",
  "status": true,
  "labels": [
    "vip"
  ],
  "passwordUpdate": "2020-10-15T06:38:00.000+00:00",
  "email": "ada@example.com",
  "phone": "+12065550100",
  "emailVerification": false,
  "phoneVerification": false,
  "mfa": false,
  "prefs": {
    "theme": "pink",
    "timezone": "UTC"
  },
  "targets": [],
  "accessedAt": "2020-10-15T06:38:00.000+00:00",
  "impersonator": false,
  "impersonatorUserId": null
}

PATCH /v1/users/{userId}/phone

修改用户手机号。

输入:

参数位置类型必填默认/枚举说明
userIdpathstring是用户 ID
numberbodystring是新手机号,+ 开头含国家码(E.164)

输出:200,返回 user(关注 phone 字段)。完整字段见 [POST /v1/users](#post-v1users)。

字段类型说明
phonestring更新后的手机号

调用示例:

curl \
  -X PATCH \
  "https://<your-endpoint>/v1/users/66a9d8ef00f21/phone" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "number": "+8613800138000"
}'

响应示例:

{
  "$id": "66a9d8ef00f21",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "name": "Ada Lovelace",
  "password": "$argon2id$v=19$m=2048,t=4,p=3$aUZjLnliVWRINmFNTWMudg$5S+x+7uA31xFnrHFT47yFwcJeaP0w92L/4LdgrVRXxE",
  "hash": "argon2",
  "hashOptions": {
    "type": "argon2",
    "memoryCost": 65536,
    "timeCost": 4,
    "threads": 3
  },
  "registration": "2020-10-15T06:38:00.000+00:00",
  "status": true,
  "labels": [
    "vip"
  ],
  "passwordUpdate": "2020-10-15T06:38:00.000+00:00",
  "email": "ada@example.com",
  "phone": "+8613800138000",
  "emailVerification": false,
  "phoneVerification": false,
  "mfa": false,
  "prefs": {
    "theme": "pink",
    "timezone": "UTC"
  },
  "targets": [],
  "accessedAt": "2020-10-15T06:38:00.000+00:00",
  "impersonator": false,
  "impersonatorUserId": null
}

PATCH /v1/users/{userId}/status

启用或封禁用户。封禁即时生效:该用户后续请求全被拒绝;再次启用不会恢复封禁期间被吊销的 Session。

输入:

参数位置类型必填默认/枚举说明
userIdpathstring是用户 ID
statusbodyboolean是true 启用 / false 封禁目标状态

输出:200,返回 user(关注 status 字段)。完整字段见 [POST /v1/users](#post-v1users)。

字段类型说明
statusbooleanfalse 表示已封禁

调用示例:

curl \
  -X PATCH \
  "https://<your-endpoint>/v1/users/66a9d8ef00f21/status" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "status": false
}'

响应示例:

{
  "$id": "66a9d8ef00f21",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "name": "Ada Lovelace",
  "password": "$argon2id$v=19$m=2048,t=4,p=3$aUZjLnliVWRINmFNTWMudg$5S+x+7uA31xFnrHFT47yFwcJeaP0w92L/4LdgrVRXxE",
  "hash": "argon2",
  "hashOptions": {
    "type": "argon2",
    "memoryCost": 65536,
    "timeCost": 4,
    "threads": 3
  },
  "registration": "2020-10-15T06:38:00.000+00:00",
  "status": false,
  "labels": [
    "vip"
  ],
  "passwordUpdate": "2020-10-15T06:38:00.000+00:00",
  "email": "ada@example.com",
  "phone": "+12065550100",
  "emailVerification": false,
  "phoneVerification": false,
  "mfa": false,
  "prefs": {
    "theme": "pink",
    "timezone": "UTC"
  },
  "targets": [],
  "accessedAt": "2020-10-15T06:38:00.000+00:00",
  "impersonator": false,
  "impersonatorUserId": null
}

PATCH /v1/users/{userId}/verification

直接置位/清除邮箱验证状态(服务端管理动作,不发送验证邮件)。

输入:

参数位置类型必填默认/枚举说明
userIdpathstring是用户 ID
emailVerificationbodyboolean是目标验证状态

输出:200,返回 user(关注 emailVerification 字段)。完整字段见 [POST /v1/users](#post-v1users)。

字段类型说明
emailVerificationboolean置位后的邮箱验证状态

调用示例:

curl \
  -X PATCH \
  "https://<your-endpoint>/v1/users/66a9d8ef00f21/verification" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "emailVerification": true
}'

响应示例:

{
  "$id": "66a9d8ef00f21",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "name": "Ada Lovelace",
  "password": "$argon2id$v=19$m=2048,t=4,p=3$aUZjLnliVWRINmFNTWMudg$5S+x+7uA31xFnrHFT47yFwcJeaP0w92L/4LdgrVRXxE",
  "hash": "argon2",
  "hashOptions": {
    "type": "argon2",
    "memoryCost": 65536,
    "timeCost": 4,
    "threads": 3
  },
  "registration": "2020-10-15T06:38:00.000+00:00",
  "status": true,
  "labels": [
    "vip"
  ],
  "passwordUpdate": "2020-10-15T06:38:00.000+00:00",
  "email": "ada@example.com",
  "phone": "+12065550100",
  "emailVerification": true,
  "phoneVerification": false,
  "mfa": false,
  "prefs": {
    "theme": "pink",
    "timezone": "UTC"
  },
  "targets": [],
  "accessedAt": "2020-10-15T06:38:00.000+00:00",
  "impersonator": false,
  "impersonatorUserId": null
}

PATCH /v1/users/{userId}/verification/phone

直接置位/清除手机验证状态(服务端管理动作,不发送验证短信)。

输入:

参数位置类型必填默认/枚举说明
userIdpathstring是用户 ID
phoneVerificationbodyboolean是目标验证状态

输出:200,返回 user(关注 phoneVerification 字段)。完整字段见 [POST /v1/users](#post-v1users)。

字段类型说明
phoneVerificationboolean置位后的手机验证状态

调用示例:

curl \
  -X PATCH \
  "https://<your-endpoint>/v1/users/66a9d8ef00f21/verification/phone" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "phoneVerification": true
}'

响应示例:

{
  "$id": "66a9d8ef00f21",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "name": "Ada Lovelace",
  "password": "$argon2id$v=19$m=2048,t=4,p=3$aUZjLnliVWRINmFNTWMudg$5S+x+7uA31xFnrHFT47yFwcJeaP0w92L/4LdgrVRXxE",
  "hash": "argon2",
  "hashOptions": {
    "type": "argon2",
    "memoryCost": 65536,
    "timeCost": 4,
    "threads": 3
  },
  "registration": "2020-10-15T06:38:00.000+00:00",
  "status": true,
  "labels": [
    "vip"
  ],
  "passwordUpdate": "2020-10-15T06:38:00.000+00:00",
  "email": "ada@example.com",
  "phone": "+12065550100",
  "emailVerification": false,
  "phoneVerification": true,
  "mfa": false,
  "prefs": {
    "theme": "pink",
    "timezone": "UTC"
  },
  "targets": [],
  "accessedAt": "2020-10-15T06:38:00.000+00:00",
  "impersonator": false,
  "impersonatorUserId": null
}

PUT /v1/users/{userId}/labels

整体替换用户标签。标签是 label:<name> 权限字符串的判定依据(见 permissions),也是列表过滤字段;本端点为全量替换语义,未列出的标签被移除。

输入:

参数位置类型必填默认/枚举说明
userIdpathstring是用户 ID
labelsbodystring[]是最多 1000 个,每个为不超过 36 位的字母数字完整的新标签数组

输出:200,返回 user(关注 labels 字段)。完整字段见 [POST /v1/users](#post-v1users)。

字段类型说明
labelsstring[]替换后的标签数组

调用示例:

curl \
  -X PUT \
  "https://<your-endpoint>/v1/users/66a9d8ef00f21/labels" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "labels": [
    "vip",
    "beta-tester"
  ]
}'

响应示例:

{
  "$id": "66a9d8ef00f21",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "name": "Ada Lovelace",
  "password": "$argon2id$v=19$m=2048,t=4,p=3$aUZjLnliVWRINmFNTWMudg$5S+x+7uA31xFnrHFT47yFwcJeaP0w92L/4LdgrVRXxE",
  "hash": "argon2",
  "hashOptions": {
    "type": "argon2",
    "memoryCost": 65536,
    "timeCost": 4,
    "threads": 3
  },
  "registration": "2020-10-15T06:38:00.000+00:00",
  "status": true,
  "labels": [
    "vip",
    "beta-tester"
  ],
  "passwordUpdate": "2020-10-15T06:38:00.000+00:00",
  "email": "ada@example.com",
  "phone": "+12065550100",
  "emailVerification": false,
  "phoneVerification": false,
  "mfa": false,
  "prefs": {
    "theme": "pink",
    "timezone": "UTC"
  },
  "targets": [],
  "accessedAt": "2020-10-15T06:38:00.000+00:00",
  "impersonator": false,
  "impersonatorUserId": null
}

PATCH /v1/users/{userId}/impersonator

设置/取消用户的受限身份(impersonator)能力。置为 true 后,该用户在客户端语境可携带 X-Appwrite-Impersonate-User-Id / X-Appwrite-Impersonate-User-Email 头,以项目内目标用户身份执行已认证请求(客服、代操作场景)。注意:模拟头只在请求本身已以某用户身份认证时有效,仅携带 X-Appwrite-Key 不足以启用;审计日志始终归属原始执行者。

输入:

参数位置类型必填默认/枚举说明
userIdpathstring是用户 ID(被授予能力的用户)
impersonatorbodyboolean是true 开启 / false 关闭

输出:200,返回 user(关注 impersonator 相关字段)。完整字段见 [POST /v1/users](#post-v1users)。

字段类型说明
impersonatorboolean是否具备模拟能力
impersonatorUserIdstring?仅当当前请求正处于模拟态时返回:原始执行者的用户 ID

调用示例:

curl \
  -X PATCH \
  "https://<your-endpoint>/v1/users/66a9d8ef00f21/impersonator" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "impersonator": true
}'

响应示例:

{
  "$id": "66a9d8ef00f21",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "name": "Ada Lovelace",
  "password": "$argon2id$v=19$m=2048,t=4,p=3$aUZjLnliVWRINmFNTWMudg$5S+x+7uA31xFnrHFT47yFwcJeaP0w92L/4LdgrVRXxE",
  "hash": "argon2",
  "hashOptions": {
    "type": "argon2",
    "memoryCost": 65536,
    "timeCost": 4,
    "threads": 3
  },
  "registration": "2020-10-15T06:38:00.000+00:00",
  "status": true,
  "labels": [
    "vip"
  ],
  "passwordUpdate": "2020-10-15T06:38:00.000+00:00",
  "email": "ada@example.com",
  "phone": "+12065550100",
  "emailVerification": false,
  "phoneVerification": false,
  "mfa": false,
  "prefs": {
    "theme": "pink",
    "timezone": "UTC"
  },
  "targets": [],
  "accessedAt": "2020-10-15T06:38:00.000+00:00",
  "impersonator": true,
  "impersonatorUserId": null
}

GET /v1/users/{userId}/prefs

读取用户偏好(自由键值 JSON,由业务侧约定语义,如主题、时区、通知开关)。

输入:

参数位置类型必填默认/枚举说明
userIdpathstring是用户 ID

输出:200,返回 preferences 键值对象。

调用示例:

curl \
  "https://<your-endpoint>/v1/users/66a9d8ef00f21/prefs" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "theme": "pink",
  "timezone": "UTC"
}

PATCH /v1/users/{userId}/prefs

合并写入用户偏好:浅合并、同键覆盖、其余键保留。

输入:

参数位置类型必填默认/枚举说明
userIdpathstring是用户 ID
prefsbodyobject是要写入的键值对象

输出:200,返回合并后的 preferences 对象。

调用示例:

curl \
  -X PATCH \
  "https://<your-endpoint>/v1/users/66a9d8ef00f21/prefs" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "prefs": {
    "theme": "dark"
  }
}'

响应示例:

{
  "theme": "dark",
  "timezone": "UTC"
}

GET /v1/users/{userId}/logs

列出用户的活动日志(该用户触发的登录、认证变更等事件),用于安全审计。

输入:

参数位置类型必填默认/枚举说明
userIdpathstring是用户 ID
queriesquerystring[]否默认 []仅支持 limit(n) 与 offset(n) 两种方法,不支持字段过滤
totalqueryboolean否默认 true传 false 跳过计数

输出:200,返回 logList 模型:total + logs[]。

字段类型说明
totalinteger日志总数
logs[]log[]日志条目,字段见下
字段类型说明
eventstring事件名(如 account.sessions.create)
userId / userEmail / userNamestring行为归属用户的 ID/邮箱/姓名;模拟(impersonation)时记录原始执行者而非被模拟用户
modestring触发时的 API 模式(如 admin)
ipstring触发时的 IP
timestring日志时间(ISO 8601)
osCode / osName / osVersion、clientType / clientCode / clientName / clientVersion / clientEngine / clientEngineVersion、deviceName / deviceBrand / deviceModelstring触发设备与客户端信息(同 session 模型)
countryCode / countryNamestring触发地理(ISO 3166-1 国家码与国家名)

调用示例:

curl \
  'https://<your-endpoint>/v1/users/66a9d8ef00f21/logs?queries[]=limit(25)&queries[]=offset(0)' \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "total": 1,
  "logs": [
    {
      "event": "account.sessions.create",
      "userId": "66a9d8ef00f21",
      "userEmail": "ada@example.com",
      "userName": "Ada Lovelace",
      "mode": "admin",
      "ip": "192.168.1.1",
      "time": "2020-10-15T06:38:00.000+00:00",
      "osCode": "Mac",
      "osName": "Mac",
      "osVersion": "10.15.6",
      "clientType": "browser",
      "clientCode": "CH",
      "clientName": "Chrome",
      "clientVersion": "84.0",
      "clientEngine": "Blink",
      "clientEngineVersion": "84.0",
      "deviceName": "desktop",
      "deviceBrand": "Apple",
      "deviceModel": "MacBook Pro",
      "countryCode": "CN",
      "countryName": "China"
    }
  ]
}

GET /v1/users/{userId}/memberships

列出用户在全部团队中的成员关系(只读视图);按用户维度排查团队权限时使用。团队侧的同一数据见 teams。

输入:

参数位置类型必填默认/枚举说明
userIdpathstring是用户 ID
queriesquerystring[]否默认 []可过滤字段:userId、teamId、invited、joined、confirm、roles
searchquerystring否模糊搜索词(最长 256 字符)
totalqueryboolean否默认 true传 false 跳过计数

输出:200,返回 membershipList 模型:total + memberships[]。membership 字段结构见 teams。

调用示例:

curl \
  'https://<your-endpoint>/v1/users/66a9d8ef00f21/memberships?queries[]=limit(25)&total=false' \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "total": 1,
  "memberships": [
    {
      "$id": "66a9d94f00e3d",
      "$createdAt": "2020-10-15T06:38:00.000+00:00",
      "$updatedAt": "2020-10-15T06:38:00.000+00:00",
      "userId": "66a9d8ef00f21",
      "userName": "Ada Lovelace",
      "userEmail": "ada@example.com",
      "teamId": "66a9d93000b1a",
      "teamName": "Platform",
      "invited": "2020-10-15T06:38:00.000+00:00",
      "joined": "2020-10-15T06:38:00.000+00:00",
      "confirm": false,
      "mfa": false,
      "roles": [
        "owner"
      ]
    }
  ]
}

POST /v1/users/{userId}/tokens

为用户签发短时 Custom Token(OTP 形态)。secret 供客户端以「token 换 Session」流程换取登录态(客户端流程不在本目录);服务端亦可用它实现自定义验证码通道。

输入:

参数位置类型必填默认/枚举说明
userIdpathstring是用户 ID
lengthbodyinteger否默认 6secret 字符数
expirebodyinteger否默认 900 秒有效期(秒)

输出:201,返回 token 模型。

字段类型说明
secretstringToken 凭证(长度即 length),仅在以 API Key 调用时返回实际值
expirestring过期时间(ISO 8601)
phrasestring安全短语(本端点未请求短语时为空串)

调用示例:

curl \
  -X POST \
  "https://<your-endpoint>/v1/users/66a9d8ef00f21/tokens" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "length": 6,
  "expire": 900
}'

响应示例:

{
  "$id": "bb8ea5c16897e",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "userId": "66a9d8ef00f21",
  "secret": "842716",
  "expire": "2020-10-15T06:38:00.000+00:00",
  "phrase": "Golden Fox"
}

POST /v1/users/{userId}/jwts

为用户的既有 Session 签发 JWT,用于向不支持 Cookie 的环境(移动端、第三方 API)传递认证。

输入:

参数位置类型必填默认/枚举说明
userIdpathstring是用户 ID
sessionIdbodystring否默认 recent(最近 Session)目标 Session ID
durationbodyinteger否默认 900 秒,最大 3600JWT 有效期(秒)

输出:201,返回 jwt 模型。

字段类型说明
jwtstring编码后的 JWT 字符串

调用示例:

curl \
  -X POST \
  "https://<your-endpoint>/v1/users/66a9d8ef00f21/jwts" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "sessionId": "66a9d9a5003c2",
  "duration": 900
}'

响应示例:

{
  "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

GET /v1/users/{userId}/sessions

列出用户的全部 Session(多端登录视图),可据此审计异常登录或做定向吊销。

输入:

参数位置类型必填默认/枚举说明
userIdpathstring是用户 ID
totalqueryboolean否默认 true传 false 跳过计数

输出:200,返回 sessionList 模型:total + sessions[]。

字段类型说明
totalintegerSession 总数
sessions[]session[]Session 对象,字段见下
字段类型说明
$idstringSession ID(游标分页与定向吊销的标识)
$createdAt / $updatedAtstring创建/最近更新时间(ISO 8601)
userIdstring所属用户 ID
expirestring过期时间(ISO 8601)
providerstring创建渠道(如 email、phone、oauth 各 Provider 名、server 等)
providerUid / providerAccessToken / providerAccessTokenExpiry / providerRefreshTokenstringOAuth 类渠道的用户标识与令牌(非 OAuth 渠道为空值)
ipstring创建 Session 时的 IP
osCode / osName / osVersionstring操作系统代码/名称/版本
clientType / clientCode / clientName / clientVersionstring客户端类型/代码/名称/版本
clientEngine / clientEngineVersionstring客户端渲染引擎与版本
deviceName / deviceBrand / deviceModelstring设备名/品牌/型号
countryCode / countryNamestringISO 3166-1 两位国家码与国家名
currentboolean是否为当前请求所属 Session(服务端视角恒为 false)
factorsstring[]已通过的认证因子(如 email、totp)
secretstringSession 凭证,仅当请求携带 API Key 时返回
mfaUpdatedAtstring最近一次通过 MFA 挑战的时间(ISO 8601)

调用示例:

curl \
  "https://<your-endpoint>/v1/users/66a9d8ef00f21/sessions" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "total": 1,
  "sessions": [
    {
      "$id": "66a9d9a5003c2",
      "$createdAt": "2020-10-15T06:38:00.000+00:00",
      "$updatedAt": "2020-10-15T06:38:00.000+00:00",
      "userId": "66a9d8ef00f21",
      "expire": "2020-10-15T06:38:00.000+00:00",
      "provider": "email",
      "providerUid": "ada@example.com",
      "providerAccessToken": "MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3",
      "providerAccessTokenExpiry": "2020-10-15T06:38:00.000+00:00",
      "providerRefreshToken": "MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3",
      "ip": "192.168.1.1",
      "osCode": "Mac",
      "osName": "Mac",
      "osVersion": "10.15.6",
      "clientType": "browser",
      "clientCode": "CH",
      "clientName": "Chrome",
      "clientVersion": "84.0",
      "clientEngine": "Blink",
      "clientEngineVersion": "84.0",
      "deviceName": "desktop",
      "deviceBrand": "Apple",
      "deviceModel": "MacBook Pro",
      "countryCode": "CN",
      "countryName": "China",
      "current": false,
      "factors": [
        "email"
      ],
      "secret": "aWtUMlRDMzlNZUpDZ1BQSkRPVUtHUG9SWmh1RlhtdVo=",
      "mfaUpdatedAt": "2020-10-15T06:38:00.000+00:00"
    }
  ]
}

POST /v1/users/{userId}/sessions

为用户直接创建 Session(服务端登录,无密码校验)——内部工具替用户建立会话、测试多端行为时使用;常规登录走客户端认证流。

输入:

参数位置类型必填默认/枚举说明
userIdpathstring是用户 ID

输出:201,返回 session 模型,字段结构见 [GET /v1/users/{userId}/sessions](#get-v1usersuseridsessions)。

调用示例:

curl \
  -X POST \
  "https://<your-endpoint>/v1/users/66a9d8ef00f21/sessions" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "$id": "66a9d9a5003c2",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "userId": "66a9d8ef00f21",
  "expire": "2020-10-15T06:38:00.000+00:00",
  "provider": "server",
  "providerUid": "ada@example.com",
  "providerAccessToken": "MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3",
  "providerAccessTokenExpiry": "2020-10-15T06:38:00.000+00:00",
  "providerRefreshToken": "MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3",
  "ip": "192.168.1.1",
  "osCode": "Mac",
  "osName": "Mac",
  "osVersion": "10.15.6",
  "clientType": "browser",
  "clientCode": "CH",
  "clientName": "Chrome",
  "clientVersion": "84.0",
  "clientEngine": "Blink",
  "clientEngineVersion": "84.0",
  "deviceName": "desktop",
  "deviceBrand": "Apple",
  "deviceModel": "MacBook Pro",
  "countryCode": "CN",
  "countryName": "China",
  "current": false,
  "factors": [
    "email"
  ],
  "secret": "aWtUMlRDMzlNZUpDZ1BQSkRPVUtHUG9SWmh1RlhtdVo=",
  "mfaUpdatedAt": "2020-10-15T06:38:00.000+00:00"
}

DELETE /v1/users/{userId}/sessions

吊销该用户的全部 Session(全端强制下线)。常与密码重置配合使用。

输入:

参数位置类型必填默认/枚举说明
userIdpathstring是用户 ID

输出:204 No Content,无响应体。

调用示例:

curl \
  -X DELETE \
  "https://<your-endpoint>/v1/users/66a9d8ef00f21/sessions" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

DELETE /v1/users/{userId}/sessions/{sessionId}

吊销用户的单个 Session(单端下线,如丢失设备场景)。

输入:

参数位置类型必填默认/枚举说明
userIdpathstring是用户 ID
sessionIdpathstring是Session ID(来自 session 列表)

输出:204 No Content,无响应体。

调用示例:

curl \
  -X DELETE \
  "https://<your-endpoint>/v1/users/66a9d8ef00f21/sessions/66a9d9a5003c2" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

GET /v1/users/{userId}/mfa/factors

列出用户已配置的 MFA 因子。

输入:

参数位置类型必填默认/枚举说明
userIdpathstring是用户 ID

输出:200,返回 mfaFactors 模型。

调用示例:

curl \
  "https://<your-endpoint>/v1/users/66a9d8ef00f21/mfa/factors" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "totp": true,
  "phone": true,
  "email": true,
  "recoveryCode": true
}

PATCH /v1/users/{userId}/mfa

整体开关用户 MFA。关闭后该用户登录不再要求第二因子,但已配置的认证器与恢复码保留。

输入:

参数位置类型必填默认/枚举说明
userIdpathstring是用户 ID
mfabodyboolean是true 开启 / false 关闭

输出:200,返回 user(关注 mfa 字段)。完整字段见 [POST /v1/users](#post-v1users)。

字段类型说明
mfaboolean置位后的 MFA 状态

调用示例:

curl \
  -X PATCH \
  "https://<your-endpoint>/v1/users/66a9d8ef00f21/mfa" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "mfa": false
}'

响应示例:

{
  "$id": "66a9d8ef00f21",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "name": "Ada Lovelace",
  "password": "$argon2id$v=19$m=2048,t=4,p=3$aUZjLnliVWRINmFNTWMudg$5S+x+7uA31xFnrHFT47yFwcJeaP0w92L/4LdgrVRXxE",
  "hash": "argon2",
  "hashOptions": {
    "type": "argon2",
    "memoryCost": 65536,
    "timeCost": 4,
    "threads": 3
  },
  "registration": "2020-10-15T06:38:00.000+00:00",
  "status": true,
  "labels": [
    "vip"
  ],
  "passwordUpdate": "2020-10-15T06:38:00.000+00:00",
  "email": "ada@example.com",
  "phone": "+12065550100",
  "emailVerification": false,
  "phoneVerification": false,
  "mfa": false,
  "prefs": {
    "theme": "pink",
    "timezone": "UTC"
  },
  "targets": [],
  "accessedAt": "2020-10-15T06:38:00.000+00:00",
  "impersonator": false,
  "impersonatorUserId": null
}

DELETE /v1/users/{userId}/mfa/authenticators/{type}

删除用户的 TOTP 认证器;用户此后需重新绑定 TOTP 或改用其他因子。

输入:

参数位置类型必填默认/枚举说明
userIdpathstring是用户 ID
typepathstring是仅 totp认证器类型

输出:204 No Content,无响应体。

调用示例:

curl \
  -X DELETE \
  "https://<your-endpoint>/v1/users/66a9d8ef00f21/mfa/authenticators/totp" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

GET /v1/users/{userId}/mfa/recovery-codes

读取用户当前有效的 MFA 恢复码。

输入:

参数位置类型必填默认/枚举说明
userIdpathstring是用户 ID

输出:200,返回 mfaRecoveryCodes 模型。

字段类型说明
recoveryCodesstring[]恢复码数组,每码仅可使用一次

调用示例:

curl \
  "https://<your-endpoint>/v1/users/66a9d8ef00f21/mfa/recovery-codes" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "recoveryCodes": [
    "a3kf0-s0cl2",
    "s0co1-as98s"
  ]
}

PATCH /v1/users/{userId}/mfa/recovery-codes

首次生成 MFA 恢复码(已存在时返回 409,改用 PUT 重新生成)。

输入:

参数位置类型必填默认/枚举说明
userIdpathstring是用户 ID

输出:201,返回 mfaRecoveryCodes 模型。

调用示例:

curl \
  -X PATCH \
  "https://<your-endpoint>/v1/users/66a9d8ef00f21/mfa/recovery-codes" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "recoveryCodes": [
    "a3kf0-s0cl2",
    "s0co1-as98s"
  ]
}

PUT /v1/users/{userId}/mfa/recovery-codes

重新生成 MFA 恢复码并整体覆盖旧码(旧码全部失效)。

输入:

参数位置类型必填默认/枚举说明
userIdpathstring是用户 ID

输出:200,返回 mfaRecoveryCodes 模型。

调用示例:

curl \
  -X PUT \
  "https://<your-endpoint>/v1/users/66a9d8ef00f21/mfa/recovery-codes" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "recoveryCodes": [
    "zx1v2-k4m5n",
    "q7w8e-r9t0y"
  ]
}

GET /v1/users/identities

列出项目内全部 OAuth/OIDC 身份(跨用户的第三方登录绑定视图),用于排查「同一第三方账号被多个用户绑定」等问题。

输入:

参数位置类型必填默认/枚举说明
queriesquerystring[]否默认 []可过滤字段:userId、provider、providerUid、providerEmail、providerAccessTokenExpiry
searchquerystring否模糊搜索词(最长 256 字符)
totalqueryboolean否默认 true传 false 跳过计数

输出:200,返回 identityList 模型:total + identities[]。

字段类型说明
totalinteger身份总数
identities[]identity[]身份对象,字段见下
字段类型说明
$idstring身份 ID
$createdAt / $updatedAtstring创建/更新时间(ISO 8601)
userIdstring关联的本地用户 ID
providerstring身份提供方(OAuth/OIDC Provider 名)
providerUidstring用户在提供方侧的 ID
providerEmailstring用户在提供方侧的邮箱
providerAccessToken / providerAccessTokenExpiry / providerRefreshTokenstring提供方访问令牌、过期时间与刷新令牌

调用示例:

curl \
  'https://<your-endpoint>/v1/users/identities?queries[]=limit(25)&queries[]=equal("provider","github")&total=false' \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "total": 1,
  "identities": [
    {
      "$id": "66a9d96700f4e",
      "$createdAt": "2020-10-15T06:38:00.000+00:00",
      "$updatedAt": "2020-10-15T06:38:00.000+00:00",
      "userId": "66a9d8ef00f21",
      "provider": "github",
      "providerUid": "10241284",
      "providerEmail": "ada@example.com",
      "providerAccessToken": "MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3",
      "providerAccessTokenExpiry": "2020-10-15T06:38:00.000+00:00",
      "providerRefreshToken": "MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3"
    }
  ]
}

DELETE /v1/users/identities/{identityId}

删除一条 OAuth 身份绑定。删除后该用户无法再用对应第三方账号登录(本地凭据不受影响)。

输入:

参数位置类型必填默认/枚举说明
identityIdpathstring是身份 ID(来自身份列表)

输出:204 No Content,无响应体。

调用示例:

curl \
  -X DELETE \
  "https://<your-endpoint>/v1/users/identities/66a9d96700f4e" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

POST /v1/users/{userId}/targets

创建用户消息目标(邮件地址、手机号或推送 token 的投递端点),供消息发送服务引用;一个用户可有多个目标。

输入:

参数位置类型必填默认/枚举说明
userIdpathstring是用户 ID
targetIdbodystring是目标 ID:自定义或传 unique();字符约束同用户 ID,最长 36 字符
providerTypebodystring是email / sms / push目标类型
identifierbodystring是投递标识:email 目标填邮箱、sms 填 E.164 手机号、push 填推送 token
providerIdbodystring否指定发送 provider;不传则使用第一个配置的同类型 provider
namebodystring否目标名称,最长 128 字符(如 Ada iPhone 12)

输出:201,返回 target 模型。

字段类型说明
$idstring目标 ID
providerType / identifier / providerIdstring回显创建参数
expiredboolean目标是否已失效
字段类型说明
$idstring目标 ID
$createdAt / $updatedAtstring创建/更新时间(ISO 8601)
namestring目标名称
userIdstring所属用户 ID
providerIdstring发送所用 provider ID
providerTypestring目标类型:email / sms / push
identifierstring投递标识(邮箱、手机号或推送 token)
expiredboolean目标是否已失效(如推送 token 被客户端废弃)

调用示例:

curl \
  -X POST \
  "https://<your-endpoint>/v1/users/66a9d8ef00f21/targets" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "targetId": "66a9d97e01a5b",
  "providerType": "email",
  "identifier": "ada@example.com",
  "providerId": "sendgrid",
  "name": "Ada iPhone 12"
}'

响应示例:

{
  "$id": "66a9d97e01a5b",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "name": "Ada iPhone 12",
  "userId": "66a9d8ef00f21",
  "providerId": "sendgrid",
  "providerType": "email",
  "identifier": "ada@example.com",
  "expired": false
}

GET /v1/users/{userId}/targets/{targetId}

按 ID 获取用户消息目标。

输入:

参数位置类型必填默认/枚举说明
userIdpathstring是用户 ID
targetIdpathstring是目标 ID

输出:200,返回 target 模型,字段见 [POST /v1/users/{userId}/targets](#post-v1usersuseridtargets)。

调用示例:

curl \
  "https://<your-endpoint>/v1/users/66a9d8ef00f21/targets/66a9d97e01a5b" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "$id": "66a9d97e01a5b",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "name": "Ada iPhone 12",
  "userId": "66a9d8ef00f21",
  "providerId": "sendgrid",
  "providerType": "email",
  "identifier": "ada@example.com",
  "expired": false
}

GET /v1/users/{userId}/targets

列出用户的消息目标。

输入:

参数位置类型必填默认/枚举说明
userIdpathstring是用户 ID
queriesquerystring[]否默认 []可过滤字段:userId、providerId、identifier、providerType
totalqueryboolean否默认 true传 false 跳过计数

输出:200,返回 targetList 模型:total + targets[]。target 字段见 [POST /v1/users/{userId}/targets](#post-v1usersuseridtargets)。

调用示例:

curl \
  'https://<your-endpoint>/v1/users/66a9d8ef00f21/targets?queries[]=limit(25)&total=false' \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "total": 1,
  "targets": [
    {
      "$id": "66a9d97e01a5b",
      "$createdAt": "2020-10-15T06:38:00.000+00:00",
      "$updatedAt": "2020-10-15T06:38:00.000+00:00",
      "name": "Ada iPhone 12",
      "userId": "66a9d8ef00f21",
      "providerId": "sendgrid",
      "providerType": "email",
      "identifier": "ada@example.com",
      "expired": false
    }
  ]
}

PATCH /v1/users/{userId}/targets/{targetId}

更新用户消息目标(换绑投递标识、改发送 provider 或改名)。

输入:

参数位置类型必填默认/枚举说明
userIdpathstring是用户 ID
targetIdpathstring是目标 ID
identifierbodystring否新投递标识(邮箱 / 手机号 / 推送 token)
providerIdbodystring否新的发送 provider ID
namebodystring否新名称,最长 128 字符

输出:200,返回 target 模型。

调用示例:

curl \
  -X PATCH \
  "https://<your-endpoint>/v1/users/66a9d8ef00f21/targets/66a9d97e01a5b" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "identifier": "ada-new@example.com"
}'

响应示例:

{
  "$id": "66a9d97e01a5b",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "$updatedAt": "2020-10-15T06:38:00.000+00:00",
  "name": "Ada iPhone 12",
  "userId": "66a9d8ef00f21",
  "providerId": "sendgrid",
  "providerType": "email",
  "identifier": "ada-new@example.com",
  "expired": false
}

DELETE /v1/users/{userId}/targets/{targetId}

删除用户消息目标(如推送 token 失效后的清理)。

输入:

参数位置类型必填默认/枚举说明
userIdpathstring是用户 ID
targetIdpathstring是目标 ID

输出:204 No Content,无响应体。

调用示例:

curl \
  -X DELETE \
  "https://<your-endpoint>/v1/users/66a9d8ef00f21/targets/66a9d97e01a5b" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

错误与边界

与 Server SDK 的对应

service.method端点
Users.listGET /users
Users.createPOST /users
Users.createArgon2UserPOST /users/argon2
Users.createBcryptUserPOST /users/bcrypt
Users.createMD5UserPOST /users/md5
Users.createPHPassUserPOST /users/phpass
Users.createScryptUserPOST /users/scrypt
Users.createScryptModifiedUserPOST /users/scrypt-modified
Users.createSHAUserPOST /users/sha
Users.getGET /users/{userId}
Users.deleteDELETE /users/{userId}
Users.updateEmailPATCH /users/{userId}/email
Users.updateNamePATCH /users/{userId}/name
Users.updatePasswordPATCH /users/{userId}/password
Users.updatePhonePATCH /users/{userId}/phone
Users.updateStatusPATCH /users/{userId}/status
Users.updateEmailVerificationPATCH /users/{userId}/verification
Users.updatePhoneVerificationPATCH /users/{userId}/verification/phone
Users.updateLabelsPUT /users/{userId}/labels
Users.updateImpersonatorPATCH /users/{userId}/impersonator
Users.getPrefsGET /users/{userId}/prefs
Users.updatePrefsPATCH /users/{userId}/prefs
Users.listLogsGET /users/{userId}/logs
Users.listMembershipsGET /users/{userId}/memberships
Users.createTokenPOST /users/{userId}/tokens
Users.createJWTPOST /users/{userId}/jwts
Users.listSessionsGET /users/{userId}/sessions
Users.createSessionPOST /users/{userId}/sessions
Users.deleteSessionsDELETE /users/{userId}/sessions
Users.deleteSessionDELETE /users/{userId}/sessions/{sessionId}
Users.listMfaFactorsGET /users/{userId}/mfa/factors
Users.updateMfaPATCH /users/{userId}/mfa
Users.deleteMfaAuthenticatorDELETE /users/{userId}/mfa/authenticators/{type}
Users.getMfaRecoveryCodesGET /users/{userId}/mfa/recovery-codes
Users.createMfaRecoveryCodesPATCH /users/{userId}/mfa/recovery-codes
Users.updateMfaRecoveryCodesPUT /users/{userId}/mfa/recovery-codes
Users.listIdentitiesGET /users/identities
Users.deleteIdentityDELETE /users/identities/{identityId}
Users.listTargetsGET /users/{userId}/targets
Users.createTargetPOST /users/{userId}/targets
Users.getTargetGET /users/{userId}/targets/{targetId}
Users.updateTargetPATCH /users/{userId}/targets/{targetId}
Users.deleteTargetDELETE /users/{userId}/targets/{targetId}

事实源