用户管理
这是什么 / 何时用
项目内用户的全生命周期管理(管理员视角):创建 / 查询 / 更新 / 停用 / 删除用户,管理登录身份、会话、MFA 因子、推送目标与标签,以及为 Custom Token 登录签发短期 token。何时用:后台账号运营、自动化引导、Custom Token 签发、会话治理。
前置
Server API Key:
users.read/users.write(会话操作相关另有 sessions scope)。管理员视角与用户「自己改自己」的账号面(profile.md)边界不同:这里操作的是任意项目用户。
使用骨架
创建用户:
users.create({ userId, email, phone, password, name })(email、phone、password、name均可选)(password 至少 8 位;ID.unique()或自定义 ID);迁移带预哈希口令的账号用createArgon2User/createBcryptUser/createMD5User/createPHPassUser。查询:
users.list({ queries, search, total })(queries、search、total均可选)(支持按关键词搜索、分页);users.get(userId)单查。更新:
updateEmail/updatePassword/updatePhone/updateName/updatePrefs;状态与验证:updateStatus(停用 / 启用)、updateEmailVerification/updatePhoneVerification。身份与标签:
listIdentities查看已绑定的 OAuth / 外部身份,deleteIdentity解绑;labels 用于基于标签的角色授权(Role.label),由管理面维护。会话治理:
listSessions/createSession/deleteSession/deleteSessions。服务端创建的会话 secret 不在响应体,只落在a_session_<projectId>Cookie;需要用户态 client 时读取该 Cookie 再Client().setSession(secret)。Custom Token 签发:业务后端完成外部身份校验后
users.createToken({ userId }),把一次性secret交给前端account.createSession({ userId, secret })换取正式 Session(流程见 authentication.md)。用户 JWT:
users.createJWT为用户签发短期 JWT(服务端编排场景)。MFA 管理:
listMfaFactors/deleteMfaAuthenticator/createMfaRecoveryCodes/getMfaRecoveryCodes/updateMfaRecoveryCodes——管理员代用户重置认证器 / 恢复码。推送目标:
createTarget/listTargets/getTarget/updateTarget/deleteTarget(配合 Messaging 的用户定向投递)。审计:
listLogs用户级操作日志;listMemberships该用户加入的团队。
关键参数与返回
| 调用 | 关键参数 | 返回 |
|---|---|---|
create | userId、email(可选)、phone(可选)、password(可选)、name(可选) | Models.User($id、email、labels、status…) |
list | queries(可选;Query.limit/offset/orderDesc 等)、search(可选)、total(可选) | UserList(users + total) |
createToken | userId | Token(一次性 secret,短时效) |
createSession | userId | Session(secret 仅在 Cookie) |
createJWT | userId | { jwt } |
updatePrefs | userId、prefs 对象 | User |
Java 侧同步返回 typed model,行内业务数据默认 Map<String,Object>,可传 Type 反序列化为 POJO;Python 侧为 snake_case 同构方法。
错误与边界
409:
userId/email/phone已存在;400:密码策略不满足。users.createToken的secret只出现一次、短时效,传输走受控通道,绝不落日志。updateStatus停用立即阻断该用户会话;删除用户是不可逆操作(关联数据清理由平台删除策略处理)。服务端为用户建会话后拿不到 secret(只在 Cookie),别试图从响应体解析。
用户全局唯一于项目;跨项目的同名用户是不同实体。
SDK 类别差异
Server SDK:本页主体(全生命周期 + Custom Token / JWT 签发)。
Client SDK:无用户管理能力(不能列用户 / 改他人);账号自身操作走 profile.md。
Console SDK:不承担项目用户管理;Console 视角的账号 / 成员见 organization.md。
各语言调用示例
以下按使用骨架逐项给出各语言调用示例;每个卡片可切换语言(全页同步)。
创建与查询
全页无 Web / Console 页签:Client SDK 无用户管理能力(不能列用户 / 改他人),账号自身操作见 profile.md;Console SDK 亦不承担项目用户管理。本卡同时覆盖创建(含预哈希口令迁移导入)与查询。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
import { Client, Users, ID, Query } from 'agentbase-node-sdk';
const client = new Client()
.setEndpoint(process.env.APPBASE_ENDPOINT!) // 必须包含 /v1
.setProject(process.env.APPBASE_PROJECT_ID!)
.setKey(process.env.APPBASE_API_KEY!); // users.read / users.write 最小 scope
const users = new Users(client);
const user = await users.create({
userId: ID.unique(), // 或自定义 ID;email/phone/userId 重复返回 409
email: 'user@example.com',
password: '<password>', // 明文,至少 8 字符;服务端哈希存储
name: 'Example User',
});
const page = await users.list({ queries: [Query.limit(25)], search: 'user@example.com' });
const one = await users.get('<userId>');
// 预哈希口令迁移导入:createArgon2User / createBcryptUser / createMD5User / createPHPassUser(传源系统哈希串,服务端不再哈希)import io.agentbase.ID;
import io.agentbase.Query;
import io.agentbase.services.Users;
Users users = new Users(client); // client 初始化见 server-sdk/java.md
var user = users.create(
ID.unique(), // userId:或自定义 ID;email/phone/userId 重复返回 409
"user@example.com", // email
null, // phone
"<password>", // password:明文,至少 8 字符;服务端哈希存储
"Example User" // name
);
var page = users.list(List.of(Query.limit(25)), "user@example.com", null); // queries / search / total
var one = users.get("<userId>");
// 预哈希口令迁移导入(位置参数 userId / email / password / name,传源系统哈希串,服务端不再哈希):
var migrated = users.createArgon2User("migrated-1", "legacy@example.com", "<argon2-hash>", "Legacy User");
// createBcryptUser / createMD5User / createPHPassUser 同构(/users/bcrypt、/md5、/phpass)from agentbase.id import ID
from agentbase.query import Query
from agentbase.services.users import Users
users = Users(client) # 同步调用,返回 pydantic 模型
created = users.create(
user_id=ID.unique(), # 或自定义 ID;email/phone/user_id 重复返回 409
email='user@example.com',
password='<password>', name='Example User')
page = users.list(queries=[Query.limit(25)], search='user@example.com')
one = users.get(user_id='<user_id>')
# 预哈希口令迁移导入(传源系统哈希串,服务端不再哈希):
migrated = users.create_argon2_user(
user_id='migrated-1', email='legacy@example.com',
password='<argon2-hash>', name='Legacy User')
# create_bcrypt_user / create_md5_user / create_ph_pass_user 同构(注意 ph_pass 拼写)users := agentbase.NewUsers(cl) // facade 构造器;cl 为已装载 API Key 的 Client
created, err := users.Create(id.Unique(),
users.WithCreateEmail("user@example.com"),
users.WithCreatePassword("<password>"),
users.WithCreateName("Example User"))
_ = created
page, err := users.List( // 可选参数按 With<方法名><参数名> 规则
users.WithListQueries([]string{query.Limit(25)}),
users.WithListSearch("user@example.com"))
one, err := users.Get("user-123")
migrated, err := users.CreateArgon2User("migrated-1", "legacy@example.com",
"<argon2-hash>", users.WithCreateArgon2UserName("Legacy User")) // 传源系统哈希串,服务端不再哈希
_, _ = page, one, migrated
// CreateBcryptUser / CreateMD5User / CreatePHPassUser 同构(UserId / Email / Password 位置参数 + Name option)curl -sS -X POST "$APPBASE_ENDPOINT/users" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"userId":"user-123","email":"user@example.com","password":"<password>","name":"Example User"}'
# 返回 201;email/phone/userId 已存在返回 409 user_already_exists
# 列表(支持 search 模糊搜索、total=false 跳过计数):
curl -sS "$APPBASE_ENDPOINT/users?queries[]=limit(25)&search=user@example.com&total=false" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY"更新、封禁与删除
updateStatus 封禁(false)即时生效;updatePrefs 合并写入偏好;updateEmail 不自动改写邮箱验证态。删除用户不可逆:级联删除其全部 Session、OAuth 身份、消息目标与团队成员关系,删除后 ID 可复用。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
await users.updateEmail({ userId: '<userId>', email: 'new@example.com' });
await users.updateStatus({ userId: '<userId>', status: false }); // 封禁;true 重新启用
await users.updatePrefs({ userId: '<userId>', prefs: { theme: 'dark' } });
await users.delete({ userId: '<userId>' }); // 不可逆;级联删除 Session、身份、目标与团队成员关系users.updateEmail("<userId>", "new@example.com"); // 不自动改写邮箱验证态
users.updateStatus("<userId>", false); // 封禁;true 重新启用,即时生效
users.updatePrefs("<userId>", Map.of("theme", "dark")); // 合并写入偏好
users.delete("<userId>"); // 不可逆;级联删除 Session、身份、目标与团队成员关系users.update_email(user_id='<user_id>', email='new@example.com') # 不自动改写邮箱验证态
users.update_status(user_id='<user_id>', status=False) # 封禁;True 重新启用
users.update_prefs(user_id='<user_id>', prefs={'theme': 'dark'}) # 合并写入偏好
users.delete(user_id='<user_id>') # 不可逆;级联删除 Session、身份、目标与团队成员关系_, err = users.UpdateEmail("user-123", "new@example.com") // 不自动改写邮箱验证态
_, err = users.UpdateStatus("user-123", false) // 封禁;true 重新启用
_, err = users.UpdatePrefs("user-123",
map[string]interface{}{"theme": "dark"}) // 合并写入偏好
_, err = users.Delete("user-123") // 不可逆;级联删除 Session、身份、目标与团队成员关系curl -sS -X PATCH "$APPBASE_ENDPOINT/users/user-123/email" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"email":"new@example.com"}'
# 封禁/启用:PATCH /users/{userId}/status,body {"status": false}(封禁即时生效)
# 偏好:PATCH /users/{userId}/prefs,body 为合并写入的键值对象
# 密码:PATCH /users/{userId}/password;手机:PATCH /users/{userId}/phone;姓名:PATCH /users/{userId}/name
# 验证态(不发验证邮件/短信):PATCH /users/{userId}/verification、PATCH /users/{userId}/verification/phone
# 删除用户:DELETE /users/{userId}(级联删除 Session、身份、目标与成员关系;删除后 ID 可复用)Custom Token 与 JWT 签发
createToken 为用户签发一次性短时 secret(默认 6 位、900 秒,OTP 形态),前端以 account.createSession({ userId, secret }) 换取正式 Session;createJWT 为既有 Session 签发短期 JWT(默认 900 秒、上限 3600)。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
const token = await users.createToken({ userId: '<userId>' }); // { secret, expire };secret 只出现一次,走受控通道
const jwt = await users.createJWT({ userId: '<userId>' }); // { jwt };为既有 Session 签发import io.agentbase.models.Token;
Token token = users.createToken("<userId>", null, null); // length / expire 可空;secret 只出现一次
var jwt = users.createJWT("<userId>", null, null); // sessionId / duration 可空;短期 JWT(默认 900 秒),为既有 Session 签发token = users.create_token(user_id='<user_id>') # { secret, expire };secret 只出现一次,走受控通道
jwt = users.create_jwt(user_id='<user_id>') # 短期 JWT(默认 900 秒),为既有 Session 签发token, err := users.CreateToken("user-123") // { secret, expire };secret 只出现一次,走受控通道
jwt, err := users.CreateJWT("user-123") // 短期 JWT(默认 900 秒),为既有 Session 签发
_, _ = token, jwtcurl -sS -X POST "$APPBASE_ENDPOINT/users/user-123/tokens" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"length":6,"expire":900}'
# 返回 201 token 模型(secret 仅以 API Key 调用时返回实际值)
# JWT:POST /users/{userId}/jwts,body {"sessionId":"<sessionId>","duration":900}(默认最近 Session,最长 3600)身份与标签
listIdentities 为项目级身份视图(排查同一第三方账号被多个用户绑定);deleteIdentity 解绑后该用户无法再用对应第三方账号登录;labels 是 label:<name> 权限判定依据,更新为整体替换语义(未列出的标签被移除)。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
const identities = await users.listIdentities({ queries: [Query.limit(25)] }); // 项目级 OAuth / 外部身份视图
await users.deleteIdentity({ identityId: '<identityId>' }); // 解绑第三方登录
await users.updateLabels('<userId>', ['admin', 'premium']); // 整体替换;未列出的标签被移除import io.agentbase.Query;
var identities = users.listIdentities(List.of(Query.limit(25)), null, null); // queries / search / total;项目级 OAuth / 外部身份视图
users.deleteIdentity("<identityId>"); // 解绑后该用户无法再用对应第三方账号登录
users.updateLabels("<userId>", List.of("admin", "premium")); // 整体替换;未列出的标签被移除identities = users.list_identities(queries=[Query.limit(25)]) # 项目级 OAuth / 外部身份视图
users.delete_identity(identity_id='<identity_id>') # 解绑后该用户无法再用对应第三方账号登录
users.update_labels(user_id='<user_id>', labels=['admin', 'premium']) # 整体替换;未列出的被移除identities, err := users.ListIdentities(
users.WithListIdentitiesQueries([]string{query.Limit(25)})) // 项目级 OAuth / 外部身份视图
_, err = users.DeleteIdentity("identity-id") // 解绑后该用户无法再用对应第三方账号登录
_, err = users.UpdateLabels("user-123", []string{"admin", "premium"}) // 整体替换;未列出的被移除
_ = identities# 项目级身份列表(跨用户第三方登录绑定视图):
curl -sS "$APPBASE_ENDPOINT/users/identities?queries[]=limit(25)" -H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY"
# 解绑:DELETE /users/identities/{identityId}
# 标签整体替换:PUT /users/{userId}/labels,body {"labels":["admin","premium"]}会话治理
服务端创建的会话 secret 不在响应体,只落在 a_session_<projectId> Cookie;需要用户态 client 时读取该 Cookie 再装载 Session。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
const sessions = await users.listSessions({ userId: '<userId>' }); // 多端登录视图,可据此审计异常登录
const created = await users.createSession({ userId: '<userId>' }); // 服务端登录(无密码校验);secret 仅在 Cookie
await users.deleteSession({ userId: '<userId>', sessionId: '<sessionId>' }); // 单端下线(如丢失设备)
await users.deleteSessions({ userId: '<userId>' }); // 全端强制下线,常与密码重置配合var sessions = users.listSessions("<userId>", null); // 多端登录视图,可据此审计异常登录
var created = users.createSession("<userId>"); // 无密码校验;secret 只落 a_session_<projectId> Cookie
users.deleteSession("<userId>", "<sessionId>"); // 单端下线(如丢失设备)
users.deleteSessions("<userId>"); // 全端强制下线,常与密码重置配合sessions = users.list_sessions(user_id='<user_id>') # 多端登录视图,可据此审计异常登录
created = users.create_session(user_id='<user_id>') # 服务端登录(无密码校验);secret 仅在 Cookie
users.delete_session(user_id='<user_id>', session_id='<session_id>') # 单端下线(如丢失设备)
users.delete_sessions(user_id='<user_id>') # 全端强制下线,常与密码重置配合sessions, err := users.ListSessions("user-123") // 多端登录视图,可据此审计异常登录
created, err := users.CreateSession("user-123") // 无密码校验;secret 只落 a_session_<projectId> Cookie
_, err = users.DeleteSession("user-123", "session-id") // 单端下线(如丢失设备)
_, err = users.DeleteSessions("user-123") // 全端强制下线,常与密码重置配合
_, _ = sessions, created# 服务端登录(无密码校验),secret 仅写 a_session_<projectId> Cookie:
curl -sS -X POST "$APPBASE_ENDPOINT/users/user-123/sessions" -H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY"
# 列表:GET /users/{userId}/sessions
# 单端下线:DELETE /users/{userId}/sessions/{sessionId};全端下线:DELETE /users/{userId}/sessionsMFA 管理
管理员代用户重置认证器与恢复码:删除 TOTP 认证器后用户需重新绑定或改用其他因子;恢复码首次生成(已存在返回 409),重新生成整体覆盖旧码。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
const factors = await users.listMfaFactors({ userId: '<userId>' }); // totp / phone / email / recoveryCode
await users.deleteMfaAuthenticator({ userId: '<userId>', type: 'totp' }); // 删除 TOTP 认证器
const codes = await users.createMfaRecoveryCodes({ userId: '<userId>' }); // 首次生成;已存在返回 409
const current = await users.getMfaRecoveryCodes({ userId: '<userId>' }); // 读取当前有效恢复码
await users.updateMfaRecoveryCodes({ userId: '<userId>' }); // 重新生成并整体覆盖旧码var factors = users.listMfaFactors("<userId>"); // totp / phone / email / recoveryCode
users.deleteMfaAuthenticator("<userId>",
io.agentbase.enums.AuthenticatorType.TOTP); // 删除后需重新绑定或改用其他因子
var codes = users.createMfaRecoveryCodes("<userId>"); // 首次生成;已存在返回 409
var current = users.getMfaRecoveryCodes("<userId>"); // 读取当前有效恢复码
users.updateMfaRecoveryCodes("<userId>"); // 重新生成并整体覆盖旧码factors = users.list_mfa_factors(user_id='<user_id>') # totp / phone / email / recoveryCode
users.delete_mfa_authenticator(user_id='<user_id>', type='totp') # 删除后需重新绑定或改用其他因子
codes = users.create_mfa_recovery_codes(user_id='<user_id>') # 首次生成;已存在返回 409
current = users.get_mfa_recovery_codes(user_id='<user_id>') # 读取当前有效恢复码
users.update_mfa_recovery_codes(user_id='<user_id>') # 重新生成并整体覆盖旧码factors, err := users.ListMfaFactors("user-123") // totp / phone / email / recoveryCode
_, err = users.DeleteMfaAuthenticator("user-123", "totp") // 删除后需重新绑定或改用其他因子
codes, err := users.CreateMfaRecoveryCodes("user-123") // 首次生成;已存在返回 409
current, err := users.GetMfaRecoveryCodes("user-123") // 读取当前有效恢复码
_, err = users.UpdateMfaRecoveryCodes("user-123") // 重新生成并整体覆盖旧码
_, _ = factors, codes
_ = current# 因子列表:GET /users/{userId}/mfa/factors
curl -sS "$APPBASE_ENDPOINT/users/user-123/mfa/factors" -H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY"
# 整体开关 MFA:PATCH /users/{userId}/mfa,body {"mfa":false}(关闭后因子与恢复码保留)
# 删除 TOTP 认证器:DELETE /users/{userId}/mfa/authenticators/totp
# 恢复码:GET 读取;PATCH 首次生成(已存在 409);PUT 重新生成并覆盖旧码推送目标
消息目标(providerType: email 邮箱 / sms E.164 手机号 / push 推送 token)是供 Messaging 定向投递引用的投递端点,一个用户可有多个目标。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
const target = await users.createTarget({
userId: '<userId>',
targetId: ID.unique(),
providerType: 'email', // email / sms / push
identifier: 'user@example.com', // 邮箱 / E.164 手机号 / 推送 token
providerId: 'sendgrid', // 可选;不传用第一个同类型 provider
name: 'Ada 主邮箱',
});
const targets = await users.listTargets({ userId: '<userId>' });
const one = await users.getTarget({ userId: '<userId>', targetId: '<targetId>' });
await users.updateTarget({ userId: '<userId>', targetId: '<targetId>', name: 'Ada 备用邮箱' });
await users.deleteTarget({ userId: '<userId>', targetId: '<targetId>' });import io.agentbase.ID;
var target = users.createTarget("<userId>", ID.unique(),
io.agentbase.enums.MessagingProviderType.EMAIL,
"user@example.com", "sendgrid", "Ada 主邮箱"); // providerType:EMAIL / SMS / PUSH 枚举
var targets = users.listTargets("<userId>", null, null);
var one = users.getTarget("<userId>", "<targetId>");
users.updateTarget("<userId>", "<targetId>",
null, null, "Ada 备用邮箱"); // identifier / providerId / name;只改名称,其余可空位传 null
users.deleteTarget("<userId>", "<targetId>");from agentbase.id import ID
target = users.create_target(
user_id='<user_id>', target_id=ID.unique(),
provider_type='email', # email / sms / push
identifier='user@example.com', # 邮箱 / E.164 手机号 / 推送 token
provider_id='sendgrid', name='Ada 主邮箱') # 可选;不传用第一个同类型 provider
targets = users.list_targets(user_id='<user_id>')
one = users.get_target(user_id='<user_id>', target_id='<target_id>')
users.update_target(user_id='<user_id>', target_id='<target_id>', name='Ada 备用邮箱')
users.delete_target(user_id='<user_id>', target_id='<target_id>')target, err := users.CreateTarget("user-123", id.Unique(), "email", "user@example.com",
users.WithCreateTargetProviderId("sendgrid"), // 可选;不传用第一个同类型 provider
users.WithCreateTargetName("Ada 主邮箱")) // ProviderType / Identifier 为位置参数:email / sms / push
targets, err := users.ListTargets("user-123")
one, err := users.GetTarget("user-123", "target-id")
_, err = users.UpdateTarget("user-123", "target-id",
users.WithUpdateTargetName("Ada 备用邮箱"))
_, err = users.DeleteTarget("user-123", "target-id")
_, _ = target, targets
_ = onecurl -sS -X POST "$APPBASE_ENDPOINT/users/user-123/targets" -H 'Content-Type: application/json' -H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY" -d '{"targetId":"push-target-1","providerType":"email","identifier":"user@example.com","providerId":"sendgrid","name":"Ada 主邮箱"}'
# 返回 201;列表 GET /users/{userId}/targets;单目标 GET/PATCH/DELETE /users/{userId}/targets/{targetId}审计与成员关系
用户级操作日志(登录、认证变更等事件)用于安全审计;成员关系是该用户在全部团队中的只读视图,团队侧同一数据见 teams.mdx。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
const logs = await users.listLogs({ userId: '<userId>' }); // 登录、认证变更等活动日志
const memberships = await users.listMemberships({ userId: '<userId>' }); // 全部团队中的成员关系var logs = users.listLogs("<userId>", null, null); // queries / total;登录、认证变更等活动日志
var memberships = users.listMemberships("<userId>", null, null, null); // queries / search / total;全部团队中的成员关系logs = users.list_logs(user_id='<user_id>') # 登录、认证变更等活动日志
memberships = users.list_memberships(user_id='<user_id>') # 全部团队中的成员关系logs, err := users.ListLogs("user-123") // 登录、认证变更等活动日志
memberships, err := users.ListMemberships("user-123") // 全部团队中的成员关系
_, _ = logs, membershipscurl -sS "$APPBASE_ENDPOINT/users/user-123/logs" -H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY"
# 成员关系只读视图:GET /users/{userId}/memberships示例指引
各语言写法集中在语言树
examples/;用户创建 / 会话 / Teams 组合的完整序列见skills/ob-agentbase/references/server-sdks/nodejs.md、skills/ob-agentbase/references/server-sdks/java.md、skills/ob-agentbase/references/server-sdks/python.md。