Docs
Contents

User Management

Feature Overview

User Management lets administrators manage the project's end-user accounts. Use Authentication → Users in the console or a server SDK to search and manage users, labels, preferences, and related sessions. Available actions depend on the current account's permissions.

By consolidating end users' basic attributes and business extension metadata (such as the vip customer tier label, the architect architect identity label, interface language, and default knowledge base preference) in Auth Users, enterprises no longer need to build redundant account-password tables, session state tables, and password hash verification logic in business databases (such as enterprise_biz_db). They can also seamlessly integrate with Agentbase's long-term memory (Memory) module — for example, an agent can automatically associate long-term conversation facts and user profiles with user_zhangwei_001 (Zhang Wei) and user_lina_002 (Li Na) directly by their User IDs.


Core Concepts and Architecture

Each Auth user entity consists of a "Core Identity" and five associated subdomains (Memberships, Identities, Targets, Sessions, Activity).

Core Concepts and Practical Example Data Table

The following fictional user profiles illustrate the fields; they do not represent data in any specific environment:

Attribute dimensionExample user 1 (enterprise VIP customer)Example user 2 (senior technical support expert)Field constraints and platform behavior notes
User ID ($id)user_zhangwei_001user_lina_002Max 36 characters; only a-z, A-Z, 0-9, ., -, _ are allowed, and the first character cannot be a special character; when left empty, the system automatically generates a unique ID.
Name张伟李娜Max 128 characters; supports Chinese and multilingual characters; can be left empty at creation and updated at any time afterward.
Emailzhangwei@customer-corp.example.comlina.support@agentbase-ops.example.comAutomatically converted to lowercase at creation and enforced as unique within the same project (a conflict returns USER_EMAIL_ALREADY_EXISTS).
Phone+8613800138001+8613900139002Must follow the E.164 standard: start with + and include the international country code, with at most 15 digits after +.
StatusVerified (email and phone verified)Verified (email verified)Includes account enabled state (Active vs the blocked red banned badge) as well as the verification status of the email/phone respectively.
Labelsvip, architectsupport, internalEach labelonly allows alphabetic and numeric characters (a-zA-Z0-9), and is automatically mapped to permission roles such as label:vip and label:architect.
Preferences{"company": "远航金融科技", "slaLevel": "P0", "preferredModel": "qwen-plus"}{"department": "企业智能客服中心", "shift": "day", "workbenchMode": "expert"}A JSON key-value object; clients can edit it via account.updatePrefs(), and administrators can edit it entry by entry in the Console.
Associated long-term memory (Memory)Extracted customer architecture preferences and OceanBase distributed transaction consultation contextConsolidated standard troubleshooting SOPs and skill distillation recordsThe Memory module indexes by user_id and builds a personalized user profile.

Roles, Entry Points, and Relationships

Console Entry Point and Permission Requirements

Relationships with Upstream and Downstream Modules

  1. Automatic creation of message targets (Targets): When an administrator clicks Create user in the Console or creates a user via the API, as long as Email is filled in, the system automatically generates a Email type Target for that user; if Phone is also filled in, a SMS type Target is automatically generated as well, directly available for Messaging and Message targets (Targets) to subscribe to topics and send notifications.

  2. Team memberships (Memberships): The Memberships tab shows all project teams the user belongs to (e.g., team_support_ops) and the team roles. After the user is removed from a team, their access to database tables (customer_tickets) and storage buckets (kb_enterprise_docs) bound with Role.team(...) is revoked immediately.

  3. Long-term memory and user profiles (Memory & Profiles): In memory management and user profiles, the system directly aggregates conversation history, long-term facts, and experience distillation results by the Auth user's User ID (e.g., user_zhangwei_001).


Feature Details and Operation Guide

1. Search and Browse the User List

Open Authentication → Users to see the project’s paginated end-user list:

User list in a test project

Figure: A synthetic example user in the user list of a 2.12.0 test project.

2. Create an End User (Create user)

In daily operations, besides end users self-registering via the frontend page, administrators can manually create internal support accounts or VIP customer accounts in the Console:

  1. On Authentication → Users, select Create user to open the form.

  2. Fill in the form for the user’s sign-in method. Leave User ID empty to generate one automatically. The service response determines the final validation result:

Dialog fieldRequiredValidation rules and input examples
NameOptionalThe user's display name, max 128 characters. Example: 张伟
EmailOptionalA valid email format; uniformly converted to lowercase before being stored on the server, and must be unique within the same project. Example: zhangwei@customer-corp.example.com
PhoneOptionalMust start with + and include the international country code, with at most 15 digits after +. Example: +8613800138001
PasswordOptionalAt least 8 characters long (server-side validation range is 8–256 characters). If the project has enabled a password dictionary or disallowed personal data in security policies, the password must also pass the corresponding compliance checks.
User IDOptionalEnter a custom ID directly in the field, or leave it empty to generate one. Example: user_zhangwei_001.
  1. Select Confirm to submit. On success, the console opens the user detail page (/auth/user-{userId}); if it fails, check the input and permissions using the displayed error.

3. Complete Guide to the Six Tabs of the User Detail Page

After entering a single user's detail page (using user_zhangwei_001 as an example), you can use the six tabs at the top for comprehensive operations management:

(1) Overview tab: basic profile, labels, preferences, and high-risk security switches

The Overview tab consists of multiple independently saved configuration cards:

Card nameCore functions and operation stepsEffect mechanism and security boundaries
Status (account status and verification)1. Click Block account to immediately ban the account (when already banned, Unblock account is shown to unblock).
2. Click Verify (or the dropdown menu) to mark Email and Phone as Verify (verified) or Unverify (unverified) respectively.
Banning an accounttakes effect immediately; all existing sessions of that user will no longer pass permission checks. Manually changing verification status does not send a verification email or SMS to the user.
Email (change email)Enter the new email address and click Update.Updates the user's bound email directly on the server side anddoes not trigger a confirmation email; the new email must likewise not conflict with other users in the project.
Phone (change phone number)Enter a new phone number in E.164 format starting with + and click Update.Updates the bound phone number directly and synchronizes the associated SMS Target.
Password (reset password)Enter the new password (at least 8 characters) and click Update.Administrators forcibly reset the user's password. If the project has enabled Invalidate sessions after password change in Security → Session security, the user's existing sessions will be invalidated simultaneously.
Labels (user labels)Enter purely alphanumeric labels in the input field (such as vip, architect), press Enter to add them, then click Update.Only letters and digits are allowed (no hyphens or underscores). After saving, the user immediately receives the Role.label('vip') and Role.label('architect') permission roles.
Preferences (key-value preferences)Click Add preference to enter Key and Value line by line (such as tier = platinum, preferredModel = qwen-plus), then click Update to save.Stored in the prefs JSON field of the user object, readable directly by the frontend via account.getPrefs(), with a total size limit of 64 KB.
User impersonationToggle the switch to allow or forbid this user from impersonating other end users in the project via the Client SDK.High-risk permission: only grant to trusted internal operations or technical support specialists (such as user_lina_002). All operations performed during impersonation are audited under the account that initiated the impersonation.
Multi-factor authenticationToggle this user's MFA enabled state; if the user has already bound an authenticator app, TOTP (One-time code) and a Delete authenticator button are displayed.When a user loses their phone and cannot generate TOTP codes, an administrator can click Delete authenticator to remove the TOTP factor (this deletion is irreversible; after removal the user must rebind).
Delete userClick the red Delete button at the bottom, verify the information in the confirmation dialog, and confirm deletion.Permanent and irreversible: completely deletes the user and all associated Sessions, Memberships, Identities, and Targets data.

(2) Memberships tab: team membership and role management

(3) Identities tab: third-party OAuth linked identities

(4) Targets tab: viewing and cleaning up notification targets

(5) Sessions tab: online device monitoring and forced sign-out

(6) Activity tab: user-level security audit trail


FAQ and Troubleshooting

Q1: When adding a label to a user in the Console, I get a format error. Why can't I input vip-customer or tier_1?

Root cause analysis: Agentbase user labels (Labels) have strict character set validation on the server side: only pure English letters and digits are allowed (a-z, A-Z, 0-9); hyphens (-), underscores (_), spaces, and Chinese characters are not supported.

Solution: Please name labels using purely alphanumeric combinations, for example vip, vipcustomer, tier1, or architect. If you need to store complex business attributes containing special characters or Chinese (such as a company name "远航金融科技" or department code "dept-01"), store them in Overview → Preferences (key-value preferences) instead.

Answer: No. When an administrator modifies the email in the Overview → Email card in the Console and clicks Update, it is a direct administrative overwrite and does not trigger an email. After the change, if the administrator confirms the new email is genuinely valid, they can click Verify → Verify email in the Status card above to switch its status directly to Verified; if you want to trigger the real verification email flow, the end user should call account.createVerification(redirectUrl) from the client.

Q3: After deleting a user, why do the support ticket records created by that user still exist in the business database table customer_tickets?

Root cause analysis: Executing Delete user in Auth → Users cascades a permanent deletion of all of that user's affiliated resources in the Auth and Messaging domains (including Sessions, Memberships, Identities, Targets), but does not automatically physically delete business rows and files in Databases or Storage, preventing the loss of core enterprise support tickets or financial ledgers caused by accidentally deleting a single customer account.

Solution: