agentbase-docs

用户管理

这是什么 / 何时用

项目内用户的全生命周期管理(管理员视角):创建 / 查询 / 更新 / 停用 / 删除用户,管理登录身份、会话、MFA 因子、推送目标与标签,以及为 Custom Token 登录签发短期 token。何时用:后台账号运营、自动化引导、Custom Token 签发、会话治理。

前置

使用骨架

关键参数与返回

调用关键参数返回
createuserId、email?、phone?、password?、name?Models.User($id、email、labels、status…)
listqueries?(Query.limit/offset/orderDesc 等)、search?、total?UserList(users + total)
createTokenuserIdToken(**一次性 secret**,短时效)
createSessionuserIdSession(secret 仅在 Cookie)
createJWTuserId{ jwt }
updatePrefsuserId、prefs 对象User

Java 侧同步返回 typed model,行内业务数据默认 Map<String,Object>,可传 Type 反序列化为 POJO;Python 侧为 snake_case 同构方法。

错误与边界

SDK 类别差异

各语言调用示例

以下按使用骨架逐项给出各语言调用示例;每个卡片可切换语言(全页同步)。

创建与查询

全页无 Web / Console 页签:Client SDK 无用户管理能力(不能列用户 / 改他人),账号自身操作见 profile.md;Console SDK 亦不承担项目用户管理。本卡同时覆盖创建(含预哈希口令迁移导入)与查询。

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(传源系统哈希串,服务端不再哈希)

更新、封禁与删除

updateStatus 封禁(false)即时生效;updatePrefs 合并写入偏好;updateEmail 不自动改写邮箱验证态。删除用户不可逆:级联删除其全部 Session、OAuth 身份、消息目标与团队成员关系,删除后 ID 可复用。

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、身份、目标与团队成员关系

Custom Token 与 JWT 签发

createToken 为用户签发一次性短时 secret(默认 6 位、900 秒,OTP 形态),前端以 account.createSession({ userId, secret }) 换取正式 Session;createJWT 为既有 Session 签发短期 JWT(默认 900 秒、上限 3600)。

const token = await users.createToken({ userId: '<userId>' });   // { secret, expire };secret 只出现一次,走受控通道
const jwt = await users.createJWT({ userId: '<userId>' });       // { jwt };为既有 Session 签发

身份与标签

listIdentities 为项目级身份视图(排查同一第三方账号被多个用户绑定);deleteIdentity 解绑后该用户无法再用对应第三方账号登录;labels 是 label:<name> 权限判定依据,更新为整体替换语义(未列出的标签被移除)。

const identities = await users.listIdentities({ queries: [Query.limit(25)] });   // 项目级 OAuth / 外部身份视图
await users.deleteIdentity({ identityId: '<identityId>' });      // 解绑第三方登录
await users.updateLabels('<userId>', ['admin', 'premium']);      // 整体替换;未列出的标签被移除

会话治理

服务端创建的会话 secret 不在响应体,只落在 a_session_<projectId> Cookie;需要用户态 client 时读取该 Cookie 再装载 Session。

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>' });                  // 全端强制下线,常与密码重置配合

MFA 管理

管理员代用户重置认证器与恢复码:删除 TOTP 认证器后用户需重新绑定或改用其他因子;恢复码首次生成(已存在返回 409),重新生成整体覆盖旧码。

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>' });                // 重新生成并整体覆盖旧码

推送目标

消息目标(providerType: email 邮箱 / sms E.164 手机号 / push 推送 token)是供 Messaging 定向投递引用的投递端点,一个用户可有多个目标。

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>' });

审计与成员关系

用户级操作日志(登录、认证变更等事件)用于安全审计;成员关系是该用户在全部团队中的只读视图,团队侧同一数据见 teams.mdx。

const logs = await users.listLogs({ userId: '<userId>' });                  // 登录、认证变更等活动日志
const memberships = await users.listMemberships({ userId: '<userId>' });    // 全部团队中的成员关系

示例指引

事实源