用户 API
用户资源的全生命周期管理接口:创建(明文密码或导入既有密码哈希)、资料与状态维护、标签与偏好、MFA、目标(推送/邮件/短信通道)、OAuth 身份、Session 与 Custom Token 签发。登录认证流(邮箱密码 / OAuth / Magic URL 的客户端换取流程)不在本目录范围,服务端侧只提供本页的管理与签发接口。
服务与资源边界
用户 API(/v1/users/*)是服务端管理项目内终端用户(如展示项目中的客户账号 user_zhangwei_001、user_lina_002)全生命周期的核心接口。它覆盖用户创建、主流密码哈希(Argon2 / Bcrypt / MD5 / PHPass / Scrypt / SHA)无感迁移导入、资料与验证状态置位、用户标签(Labels,直接驱动 label:<name> 权限判定)、自定义偏好(prefs)、多因素认证(MFA)、消息触达目标(Targets)以及服务端签发 Custom Token / Session / JWT。
资源与基础路径
Base URL:
https://<your-endpoint>/v1,路径前缀/users。资源:
user(用户)、identity(OAuth/OIDC 身份)、session(会话)、target(消息目标)、token(短时 Custom Token)、membership(团队成员关系,只读视图)。用户 ID 为自定义或自动生成的字符串(a-z、A-Z、0-9、
.、-、_,不能以特殊字符开头,最长 36 字符)。
认证与权限
认证与请求头约定见 通用约定。本域涉及的 scope:
| scope | 覆盖操作 |
|---|---|
users.read | 用户/身份/Session/日志/成员关系/MFA 因子读取 |
users.write | 创建与修改用户、密码、状态、标签、偏好、MFA 管理、Session 管理、Token/JWT 签发、身份删除 |
targets.read / targets.write | 用户 target 资源的读写 |
端点总览
Users 模块共提供 43 个端点,按职责划分为:用户创建与哈希导入(9 个)、基础资料与封禁/验证状态维护(9 个)、标签与偏好配置(3 个)、会话与令牌签发(6 个)、MFA 认证器与恢复码治理(6 个)、OAuth 身份与消息目标管理(7 个)以及活动日志与团队归属查询(3 个)。
端点清单
| 方法 + 路径 | 用途 |
|---|---|
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} | 删除消息目标 |
端点详解
标签(Labels)与权限联动:调用
PUT /v1/users/{userId}/labels整体替换用户标签数组后,该用户在访问数据库、存储桶或知识库时将立即获得对应label:<name>角色权限(详见 权限字符串文法)。密码导入与重置:通过
/users/argon2、/users/bcrypt等端点导入历史系统用户时,平台保留原密码哈希格式并在用户首次登录时校验;调用PATCH /v1/users/{userId}/password则传入明文密码由平台统一使用 Argon2 重新哈希存储。
请求与响应
以下按端点逐个给出输入、输出、可复制的调用示例与响应示例。所有示例的 <your-endpoint>、<YOUR_PROJECT_ID>、<YOUR_API_KEY> 替换为你的接入点、项目 ID 与 API Key;POST/PUT/PATCH 示例的请求体为 JSON,字段必填性与默认值以「输入」表为准。
GET /v1/users
列出项目内全部用户,支持按用户属性过滤与模糊搜索。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
queries | query | string[] | 否 | 默认 [] | Query 数组(形如 limit(25)、offset(0)、equal("status","true")),最多 100 条、每条最长 4096 字符;可过滤字段:name、email、phone、status、passwordUpdate、registration、emailVerification、phoneVerification、labels、impersonator |
search | query | string | 否 | 模糊搜索词(最长 256 字符),覆盖姓名与邮箱 | |
total | query | boolean | 否 | 默认 true | 传 false 跳过计数,total 恒返回 0 |
输出:200,返回 userList 模型:total 为匹配总数,users[] 为用户数组。分页游标取上一页最后一条的 $id 配合 cursorAfter() 使用。
| 字段 | 类型 | 说明 |
|---|---|---|
| total | integer | 匹配查询的用户总数(total=false 时恒为 0) |
| users[] | user[] | 用户对象,字段结构见 POST /v1/users 输出说明 |
调用示例:
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 补设。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
userId | body | string | 是 | 用户 ID:自定义或传 unique() 由服务端生成;可用字符 a-z、A-Z、0-9、.、-、_,不能以特殊字符开头,最长 36 字符 | |
email | body | string | 否 | 邮箱;项目内唯一,重复返回 409 user_already_exists | |
phone | body | string | 否 | 手机号,+ 开头含国家码(E.164),如 +12065550100 | |
password | body | string | 否 | 明文密码,至少 8 字符;服务端以项目默认算法(Argon2)哈希 | |
name | body | string | 否 | 姓名,最长 128 字符 |
输出:201,返回 user 模型。完整字段表:
| 字段 | 类型 | 说明 |
|---|---|---|
| $id | string | 用户 ID |
| $createdAt | string | 创建时间(ISO 8601) |
| $updatedAt | string | 最近更新时间(ISO 8601) |
| name | string | 姓名 |
| password | string? | 哈希后的密码串(管理 API 不回显明文;经哈希导入端点创建时为源系统的哈希) |
| hash | string? | 密码哈希算法名(argon2 / bcrypt / md5 / phpass / scrypt / scryptModified / sha) |
| hashOptions | object? | 哈希算法参数(algoArgon2 / algoScrypt 等,结构与 hash 对应;如 Argon2 为 type/memoryCost/timeCost/threads) |
| registration | string | 注册时间(ISO 8601) |
| status | boolean | 启用状态:true 启用、false 封禁 |
| labels | string[] | 用户标签(label:<name> 权限的判定依据) |
| passwordUpdate | string | 最近一次密码更新时间(ISO 8601) |
| string | 邮箱(未设置时为空串) | |
| phone | string | 手机号(E.164 格式,未设置时为空串) |
| emailVerification | boolean | 邮箱验证状态 |
| phoneVerification | boolean | 手机验证状态 |
| mfa | boolean | 是否启用 MFA |
| prefs | object | 偏好键值对象 |
| targets | target[] | 消息目标列表(同一结构见 targets 端点) |
| accessedAt | string | 最近访问时间(ISO 8601,24 小时内不重复刷新) |
| impersonator | boolean? | 是否具备受限身份(impersonator)能力 |
| impersonatorUserId | string? | 当前请求处于模拟态时的原始执行者用户 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 校验。适用于把既有用户体系无缝迁移到本平台。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
userId | body | string | 是 | 同 POST /v1/users 的 userId 约束 | |
email | body | string | 是 | 邮箱;项目内唯一 | |
password | body | string | 是 | 源系统的 Argon2 哈希串(如 $argon2id$v=19$m=2048,t=4,p=3$...),服务端原样存储 | |
name | body | string | 否 | 姓名,最长 128 字符 |
输出:201,返回 user;hash 字段为 argon2,hashOptions 回显哈希参数。完整字段见 POST /v1/users。
调用示例:
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。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
userId | body | string | 是 | 同 POST /v1/users 的 userId 约束 | |
email | body | string | 是 | 邮箱;项目内唯一 | |
password | body | string | 是 | 源系统的 Bcrypt 哈希串(如 $2a$12$...) | |
name | body | string | 否 | 姓名,最长 128 字符 |
输出:201,返回 user;hash 为 bcrypt。完整字段见 POST /v1/users。
调用示例:
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。MD5 已不安全,导入后建议引导用户重置密码。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
userId | body | string | 是 | 同 POST /v1/users 的 userId 约束 | |
email | body | string | 是 | 邮箱;项目内唯一 | |
password | body | string | 是 | 源系统的 MD5 哈希串(32 位十六进制,如 5f4dcc3b5aa765d61d8327deb882cf99) | |
name | body | string | 否 | 姓名,最长 128 字符 |
输出:201,返回 user;hash 为 md5。完整字段见 POST /v1/users。
调用示例:
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。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
userId | body | string | 是 | 同 POST /v1/users 的 userId 约束 | |
email | body | string | 是 | 邮箱;项目内唯一 | |
password | body | string | 是 | 源系统的 PHPass 哈希串(如 $P$B...) | |
name | body | string | 否 | 姓名,最长 128 字符 |
输出:201,返回 user;hash 为 phpass。完整字段见 POST /v1/users。
调用示例:
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 与代价参数。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
userId | body | string | 是 | 同 POST /v1/users 的 userId 约束 | |
email | body | string | 是 | 邮箱;项目内唯一 | |
password | body | string | 是 | 源系统的 Scrypt 哈希串 | |
passwordSalt | body | string | 是 | 哈希所用 salt | |
passwordCpu | body | integer | 是 | CPU 代价参数(源系统配置) | |
passwordMemory | body | integer | 是 | 内存代价参数(源系统配置) | |
passwordParallel | body | integer | 是 | 并行化参数(源系统配置) | |
passwordLength | body | integer | 是 | 哈希输出长度(源系统配置) | |
name | body | string | 否 | 姓名,最长 128 字符 |
输出:201,返回 user;hash 为 scrypt,hashOptions 回显以上参数。完整字段见 POST /v1/users。
调用示例:
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,但参数为 Firebase 特有的 salt 分隔符与签名密钥。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
userId | body | string | 是 | 同 POST /v1/users 的 userId 约束 | |
email | body | string | 是 | 邮箱;项目内唯一 | |
password | body | string | 是 | 源系统的 Scrypt Modified 哈希串(base64) | |
passwordSalt | body | string | 是 | 哈希所用 salt(base64) | |
passwordSaltSeparator | body | string | 是 | salt 分隔符(Firebase 导出字段 saltSeparator) | |
passwordSignerKey | body | string | 是 | 签名密钥(Firebase 导出字段 signerKey,base64) | |
name | body | string | 否 | 姓名,最长 128 字符 |
输出:201,返回 user;hash 为 scryptModified。完整字段见 POST /v1/users。
调用示例:
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;用 passwordVersion 指定具体变体。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
userId | body | string | 是 | 同 POST /v1/users 的 userId 约束 | |
email | body | string | 是 | 邮箱;项目内唯一 | |
password | body | string | 是 | 源系统的 SHA 哈希串(十六进制) | |
passwordVersion | body | string | 否 | sha1(默认)/ sha224 / sha256 / sha384 / sha512/224 / sha512/256 / sha512 / sha3-224 / sha3-256 / sha3-384 / sha3-512 | SHA 变体,需与源系统一致 |
name | body | string | 否 | 姓名,最长 128 字符 |
输出:201,返回 user;hash 为 sha,hashOptions 回显版本。完整字段见 POST /v1/users。
调用示例:
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 获取单个用户。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
userId | path | string | 是 | 用户 ID |
输出:200,返回 user 模型,完整字段见 POST /v1/users。
调用示例:
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 供审计。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
userId | path | string | 是 | 用户 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。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
userId | path | string | 是 | 用户 ID | |
email | body | string | 是 | 新邮箱;与其他用户冲突时返回 409 user_already_exists |
输出:200,返回 user(关注 email 字段)。完整字段见 POST /v1/users。
| 字段 | 类型 | 说明 |
|---|---|---|
| string | 更新后的邮箱 |
调用示例:
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
修改用户姓名。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
userId | path | string | 是 | 用户 ID | |
name | body | string | 是 | 新姓名,最长 128 字符 |
输出:200,返回 user(关注 name 字段)。完整字段见 POST /v1/users。
| 字段 | 类型 | 说明 |
|---|---|---|
| name | string | 更新后的姓名 |
调用示例:
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。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
userId | path | string | 是 | 用户 ID | |
password | body | string | 是 | 新明文密码,至少 8 字符 |
输出:200,返回 user(关注 passwordUpdate 字段刷新)。完整字段见 POST /v1/users。
| 字段 | 类型 | 说明 |
|---|---|---|
| passwordUpdate | string | 本次重置的时间(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
修改用户手机号。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
userId | path | string | 是 | 用户 ID | |
number | body | string | 是 | 新手机号,+ 开头含国家码(E.164) |
输出:200,返回 user(关注 phone 字段)。完整字段见 POST /v1/users。
| 字段 | 类型 | 说明 |
|---|---|---|
| phone | string | 更新后的手机号 |
调用示例:
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。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
userId | path | string | 是 | 用户 ID | |
status | body | boolean | 是 | true 启用 / false 封禁 | 目标状态 |
输出:200,返回 user(关注 status 字段)。完整字段见 POST /v1/users。
| 字段 | 类型 | 说明 |
|---|---|---|
| status | boolean | false 表示已封禁 |
调用示例:
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
直接置位/清除邮箱验证状态(服务端管理动作,不发送验证邮件)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
userId | path | string | 是 | 用户 ID | |
emailVerification | body | boolean | 是 | 目标验证状态 |
输出:200,返回 user(关注 emailVerification 字段)。完整字段见 POST /v1/users。
| 字段 | 类型 | 说明 |
|---|---|---|
| emailVerification | boolean | 置位后的邮箱验证状态 |
调用示例:
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
直接置位/清除手机验证状态(服务端管理动作,不发送验证短信)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
userId | path | string | 是 | 用户 ID | |
phoneVerification | body | boolean | 是 | 目标验证状态 |
输出:200,返回 user(关注 phoneVerification 字段)。完整字段见 POST /v1/users。
| 字段 | 类型 | 说明 |
|---|---|---|
| phoneVerification | boolean | 置位后的手机验证状态 |
调用示例:
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),也是列表过滤字段;本端点为全量替换语义,未列出的标签被移除。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
userId | path | string | 是 | 用户 ID | |
labels | body | string[] | 是 | 最多 1000 个,每个为不超过 36 位的字母数字 | 完整的新标签数组 |
输出:200,返回 user(关注 labels 字段)。完整字段见 POST /v1/users。
| 字段 | 类型 | 说明 |
|---|---|---|
| labels | string[] | 替换后的标签数组 |
调用示例:
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 不足以启用;审计日志始终归属原始执行者。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
userId | path | string | 是 | 用户 ID(被授予能力的用户) | |
impersonator | body | boolean | 是 | true 开启 / false 关闭 |
输出:200,返回 user(关注 impersonator 相关字段)。完整字段见 POST /v1/users。
| 字段 | 类型 | 说明 |
|---|---|---|
| impersonator | boolean | 是否具备模拟能力 |
| impersonatorUserId | string? | 仅当当前请求正处于模拟态时返回:原始执行者的用户 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,由业务侧约定语义,如主题、时区、通知开关)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
userId | path | string | 是 | 用户 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
合并写入用户偏好:浅合并、同键覆盖、其余键保留。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
userId | path | string | 是 | 用户 ID | |
prefs | body | object | 是 | 要写入的键值对象 |
输出: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
列出用户的活动日志(该用户触发的登录、认证变更等事件),用于安全审计。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
userId | path | string | 是 | 用户 ID | |
queries | query | string[] | 否 | 默认 [] | 仅支持 limit(n) 与 offset(n) 两种方法,不支持字段过滤 |
total | query | boolean | 否 | 默认 true | 传 false 跳过计数 |
输出:200,返回 logList 模型:total + logs[]。
| 字段 | 类型 | 说明 |
|---|---|---|
| total | integer | 日志总数 |
| logs[] | log[] | 日志条目,字段见下 |
| 字段 | 类型 | 说明 |
|---|---|---|
| event | string | 事件名(如 account.sessions.create) |
| userId / userEmail / userName | string | 行为归属用户的 ID/邮箱/姓名;模拟(impersonation)时记录原始执行者而非被模拟用户 |
| mode | string | 触发时的 API 模式(如 admin) |
| ip | string | 触发时的 IP |
| time | string | 日志时间(ISO 8601) |
| osCode / osName / osVersion、clientType / clientCode / clientName / clientVersion / clientEngine / clientEngineVersion、deviceName / deviceBrand / deviceModel | string | 触发设备与客户端信息(同 session 模型) |
| countryCode / countryName | string | 触发地理(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。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
userId | path | string | 是 | 用户 ID | |
queries | query | string[] | 否 | 默认 [] | 可过滤字段:userId、teamId、invited、joined、confirm、roles |
search | query | string | 否 | 模糊搜索词(最长 256 字符) | |
total | query | boolean | 否 | 默认 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」流程换取登录态(客户端流程不在本目录);服务端亦可用它实现自定义验证码通道。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
userId | path | string | 是 | 用户 ID | |
length | body | integer | 否 | 默认 6 | secret 字符数 |
expire | body | integer | 否 | 默认 900 秒 | 有效期(秒) |
输出:201,返回 token 模型。
| 字段 | 类型 | 说明 |
|---|---|---|
| secret | string | Token 凭证(长度即 length),仅在以 API Key 调用时返回实际值 |
| expire | string | 过期时间(ISO 8601) |
| phrase | string | 安全短语(本端点未请求短语时为空串) |
调用示例:
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)传递认证。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
userId | path | string | 是 | 用户 ID | |
sessionId | body | string | 否 | 默认 recent(最近 Session) | 目标 Session ID |
duration | body | integer | 否 | 默认 900 秒,最大 3600 | JWT 有效期(秒) |
输出:201,返回 jwt 模型。
| 字段 | 类型 | 说明 |
|---|---|---|
| jwt | string | 编码后的 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(多端登录视图),可据此审计异常登录或做定向吊销。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
userId | path | string | 是 | 用户 ID | |
total | query | boolean | 否 | 默认 true | 传 false 跳过计数 |
输出:200,返回 sessionList 模型:total + sessions[]。
| 字段 | 类型 | 说明 |
|---|---|---|
| total | integer | Session 总数 |
| sessions[] | session[] | Session 对象,字段见下 |
| 字段 | 类型 | 说明 |
|---|---|---|
| $id | string | Session ID(游标分页与定向吊销的标识) |
| $createdAt / $updatedAt | string | 创建/最近更新时间(ISO 8601) |
| userId | string | 所属用户 ID |
| expire | string | 过期时间(ISO 8601) |
| provider | string | 创建渠道(如 email、phone、oauth 各 Provider 名、server 等) |
| providerUid / providerAccessToken / providerAccessTokenExpiry / providerRefreshToken | string | OAuth 类渠道的用户标识与令牌(非 OAuth 渠道为空值) |
| ip | string | 创建 Session 时的 IP |
| osCode / osName / osVersion | string | 操作系统代码/名称/版本 |
| clientType / clientCode / clientName / clientVersion | string | 客户端类型/代码/名称/版本 |
| clientEngine / clientEngineVersion | string | 客户端渲染引擎与版本 |
| deviceName / deviceBrand / deviceModel | string | 设备名/品牌/型号 |
| countryCode / countryName | string | ISO 3166-1 两位国家码与国家名 |
| current | boolean | 是否为当前请求所属 Session(服务端视角恒为 false) |
| factors | string[] | 已通过的认证因子(如 email、totp) |
| secret | string | Session 凭证,仅当请求携带 API Key 时返回 |
| mfaUpdatedAt | string | 最近一次通过 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(服务端登录,无密码校验)——内部工具替用户建立会话、测试多端行为时使用;常规登录走客户端认证流。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
userId | path | string | 是 | 用户 ID |
输出:201,返回 session 模型,字段结构见 GET /v1/users/{userId}/sessions。
调用示例:
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(全端强制下线)。常与密码重置配合使用。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
userId | path | string | 是 | 用户 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(单端下线,如丢失设备场景)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
userId | path | string | 是 | 用户 ID | |
sessionId | path | string | 是 | 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 因子。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
userId | path | string | 是 | 用户 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。关闭后该用户登录不再要求第二因子,但已配置的认证器与恢复码保留。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
userId | path | string | 是 | 用户 ID | |
mfa | body | boolean | 是 | true 开启 / false 关闭 |
输出:200,返回 user(关注 mfa 字段)。完整字段见 POST /v1/users。
| 字段 | 类型 | 说明 |
|---|---|---|
| mfa | boolean | 置位后的 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 或改用其他因子。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
userId | path | string | 是 | 用户 ID | |
type | path | string | 是 | 仅 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 恢复码。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
userId | path | string | 是 | 用户 ID |
输出:200,返回 mfaRecoveryCodes 模型。
| 字段 | 类型 | 说明 |
|---|---|---|
| recoveryCodes | string[] | 恢复码数组,每码仅可使用一次 |
调用示例:
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 重新生成)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
userId | path | string | 是 | 用户 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 恢复码并整体覆盖旧码(旧码全部失效)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
userId | path | string | 是 | 用户 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 身份(跨用户的第三方登录绑定视图),用于排查「同一第三方账号被多个用户绑定」等问题。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
queries | query | string[] | 否 | 默认 [] | 可过滤字段:userId、provider、providerUid、providerEmail、providerAccessTokenExpiry |
search | query | string | 否 | 模糊搜索词(最长 256 字符) | |
total | query | boolean | 否 | 默认 true | 传 false 跳过计数 |
输出:200,返回 identityList 模型:total + identities[]。
| 字段 | 类型 | 说明 |
|---|---|---|
| total | integer | 身份总数 |
| identities[] | identity[] | 身份对象,字段见下 |
| 字段 | 类型 | 说明 |
|---|---|---|
| $id | string | 身份 ID |
| $createdAt / $updatedAt | string | 创建/更新时间(ISO 8601) |
| userId | string | 关联的本地用户 ID |
| provider | string | 身份提供方(OAuth/OIDC Provider 名) |
| providerUid | string | 用户在提供方侧的 ID |
| providerEmail | string | 用户在提供方侧的邮箱 |
| providerAccessToken / providerAccessTokenExpiry / providerRefreshToken | string | 提供方访问令牌、过期时间与刷新令牌 |
调用示例:
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 身份绑定。删除后该用户无法再用对应第三方账号登录(本地凭据不受影响)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
identityId | path | string | 是 | 身份 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 的投递端点),供消息发送服务引用;一个用户可有多个目标。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
userId | path | string | 是 | 用户 ID | |
targetId | body | string | 是 | 目标 ID:自定义或传 unique();字符约束同用户 ID,最长 36 字符 | |
providerType | body | string | 是 | email / sms / push | 目标类型 |
identifier | body | string | 是 | 投递标识:email 目标填邮箱、sms 填 E.164 手机号、push 填推送 token | |
providerId | body | string | 否 | 指定发送 provider;不传则使用第一个配置的同类型 provider | |
name | body | string | 否 | 目标名称,最长 128 字符(如 Ada iPhone 12) |
输出:201,返回 target 模型。
| 字段 | 类型 | 说明 |
|---|---|---|
| $id | string | 目标 ID |
| providerType / identifier / providerId | string | 回显创建参数 |
| expired | boolean | 目标是否已失效 |
| 字段 | 类型 | 说明 |
|---|---|---|
| $id | string | 目标 ID |
| $createdAt / $updatedAt | string | 创建/更新时间(ISO 8601) |
| name | string | 目标名称 |
| userId | string | 所属用户 ID |
| providerId | string | 发送所用 provider ID |
| providerType | string | 目标类型:email / sms / push |
| identifier | string | 投递标识(邮箱、手机号或推送 token) |
| expired | boolean | 目标是否已失效(如推送 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 获取用户消息目标。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
userId | path | string | 是 | 用户 ID | |
targetId | path | string | 是 | 目标 ID |
输出:200,返回 target 模型,字段见 POST /v1/users/{userId}/targets。
调用示例:
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
列出用户的消息目标。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
userId | path | string | 是 | 用户 ID | |
queries | query | string[] | 否 | 默认 [] | 可过滤字段:userId、providerId、identifier、providerType |
total | query | boolean | 否 | 默认 true | 传 false 跳过计数 |
输出:200,返回 targetList 模型:total + targets[]。target 字段见 POST /v1/users/{userId}/targets。
调用示例:
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 或改名)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
userId | path | string | 是 | 用户 ID | |
targetId | path | string | 是 | 目标 ID | |
identifier | body | string | 否 | 新投递标识(邮箱 / 手机号 / 推送 token) | |
providerId | body | string | 否 | 新的发送 provider ID | |
name | body | string | 否 | 新名称,最长 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 失效后的清理)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
userId | path | string | 是 | 用户 ID | |
targetId | path | string | 是 | 目标 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>"错误与边界
用户不存在:
404+user_not_found;身份不存在:user_identity_not_found;Session 不存在:user_session_not_found;目标不存在:user_target_not_found。创建用户邮箱重复:
409+user_already_exists;POST /users不传password时创建无密码用户(后续可用updatePassword补设)。删除用户会级联删除其 Session、身份、目标与成员关系;删除后该 ID 可复用,但历史日志仍保留原 ID。
封禁(
status=false)即时生效:该用户全部后续请求被拒;再次启用不恢复被吊销的 Session。updateEmail不会自动重置emailVerification;需要同时调用updateEmailVerification。导入哈希创建时服务端不校验哈希格式与源系统一致性,错误的参数会让用户无法登录;建议导入后验证一次。
token/JWT 一旦签发即在有效期内有效,泄露等同账号可登录;按需用 Session 吊销端点收窄。
与 Server SDK 的对应
| service.method | 端点 |
|---|---|
Users.list | GET /users |
Users.create | POST /users |
Users.createArgon2User | POST /users/argon2 |
Users.createBcryptUser | POST /users/bcrypt |
Users.createMD5User | POST /users/md5 |
Users.createPHPassUser | POST /users/phpass |
Users.createScryptUser | POST /users/scrypt |
Users.createScryptModifiedUser | POST /users/scrypt-modified |
Users.createSHAUser | POST /users/sha |
Users.get | GET /users/{userId} |
Users.delete | DELETE /users/{userId} |
Users.updateEmail | PATCH /users/{userId}/email |
Users.updateName | PATCH /users/{userId}/name |
Users.updatePassword | PATCH /users/{userId}/password |
Users.updatePhone | PATCH /users/{userId}/phone |
Users.updateStatus | PATCH /users/{userId}/status |
Users.updateEmailVerification | PATCH /users/{userId}/verification |
Users.updatePhoneVerification | PATCH /users/{userId}/verification/phone |
Users.updateLabels | PUT /users/{userId}/labels |
Users.updateImpersonator | PATCH /users/{userId}/impersonator |
Users.getPrefs | GET /users/{userId}/prefs |
Users.updatePrefs | PATCH /users/{userId}/prefs |
Users.listLogs | GET /users/{userId}/logs |
Users.listMemberships | GET /users/{userId}/memberships |
Users.createToken | POST /users/{userId}/tokens |
Users.createJWT | POST /users/{userId}/jwts |
Users.listSessions | GET /users/{userId}/sessions |
Users.createSession | POST /users/{userId}/sessions |
Users.deleteSessions | DELETE /users/{userId}/sessions |
Users.deleteSession | DELETE /users/{userId}/sessions/{sessionId} |
Users.listMfaFactors | GET /users/{userId}/mfa/factors |
Users.updateMfa | PATCH /users/{userId}/mfa |
Users.deleteMfaAuthenticator | DELETE /users/{userId}/mfa/authenticators/{type} |
Users.getMfaRecoveryCodes | GET /users/{userId}/mfa/recovery-codes |
Users.createMfaRecoveryCodes | PATCH /users/{userId}/mfa/recovery-codes |
Users.updateMfaRecoveryCodes | PUT /users/{userId}/mfa/recovery-codes |
Users.listIdentities | GET /users/identities |
Users.deleteIdentity | DELETE /users/identities/{identityId} |
Users.listTargets | GET /users/{userId}/targets |
Users.createTarget | POST /users/{userId}/targets |
Users.getTarget | GET /users/{userId}/targets/{targetId} |
Users.updateTarget | PATCH /users/{userId}/targets/{targetId} |
Users.deleteTarget | DELETE /users/{userId}/targets/{targetId} |