Account Profile, Sessions, and Preferences
Overview and use cases
The read/write surface for a signed-in user's own account: profile (name, email, phone), password, preferences, login logs, push targets, identities, as well as the account-level last 30-day usage aggregation added in 2.6.0. Suitable for building "Personal Center", "Account Settings", and "Device/Session Management" pages.
Prerequisites
A usable user Session established by any sign-in method (see authentication.md).
The Client SDK (user Session) can complete the vast majority of operations on this page; a few management perspectives (blocking, labels, cross-user) belong to the Server SDK user management surface, see users.md.
Usage workflow
Read the current account:
account.get(); throws 401 when not signed in, and the frontend proceeds with the sign-in flow accordingly.Modify profile:
updateName/updateEmail(requiringpassworddepending on the scenario) /updatePhone/updatePassword(requires old credential verification).Preferences:
account.getPrefs()to read,account.updatePrefs()to merge-write arbitrary JSON key-values (frontend display preferences, language, etc.); do not put business authorization fields in preferences.Session management:
account.listSessionsto list all active sessions (including the current one),account.getSessionto query a single one,account.updateSessionto refresh a specified session,account.deleteSessionsto sign out of all,account.deleteSession('current')to sign out of the current one.Login logs:
account.listLogsto audit sign-ins and sensitive operations.Push targets:
createPushTarget/updatePushTarget/deletePushTargetto maintain message push destinations (used together with Messaging).Identities:
account.listIdentitiesto view bound OAuth/external identities,account.deleteIdentityto unlink.Email/phone verification:
account.createEmailVerification(url)→ the email confirmation callback callsaccount.updateEmailVerification({ userId, secret }); Phone corresponds tocreatePhoneVerification/updatePhoneVerification.Password recovery:
account.createRecovery(url)→account.updateRecovery({ userId, secret, password }).Account usage (2.6.0):
account.getUsageAggregates()returns aggregations of four standard Meters for the current account's last 30 UTC days (storage_bytes,bandwidth_bytes,function_executions,users_total), each Meter-Day carryingquantity/complete/freshnessAt/reason;quantity: nullmeans missing and must not be displayed as 0.
Key parameters and returns
| Call | Key parameters | Returns |
|---|---|---|
get / updateName | name (optional) | Models.User ($id, email, name, labels, prefs, etc.) |
updateEmail / updatePhone | email|phone, password (optional) | User (when converting an anonymous account, password is the new password) |
updatePassword | newPassword, oldPassword (optional) | User |
updatePrefs | Arbitrary key-value object (merge semantics) | User |
listSessions / getSession / updateSession / deleteSession(s) | sessionId (use 'current' for the current session) | Session list / Session |
listLogs | queries (optional; pagination/filtering) | Log list |
createPushTarget etc. | targetId, providerId, identifier | PushTarget |
getUsageAggregates (2.6.0) | None (fixed to the last 30 UTC days, range: '30d') | MeterUsageList (four Meters, coverage, freshness) |
Errors and boundaries
401: not signed in or Session invalid; 409 / 400: email/phone already taken, password policy not met, verification
secretinvalid or expired.updatePrefsis a merge-write; to clear a key you must explicitly set it tonull; there is no "wholesale replacement" semantics.deleteSessionsalso signs out the current session; to sign out only the current device usedeleteSession('current').Before unlinking the last identity, confirm that a usable sign-in method remains to avoid locking out the account.
The usage aggregation time window is fixed and intervals cannot be chosen; the older project / storage / TablesDB usage queries are a different methodology and should not be mixed.
SDK Category Differences
Client SDK (Web-first): the main body of this page; Sessions are restored by the SDK via three layers: Cookie / header / fallback, see client-sdk/web.md.
Server SDK: the identically named user management surface is the administrator perspective (cross-user queries, status, labels, MFA reset), not "changing your own settings", see users.md.
Console SDK: the Console account's own profile and sessions belong to the management-plane boundary and are unrelated to application user accounts.
Examples by language
The following provides examples by language, item by item along the usage workflow; each card can switch languages (synced across the page).
Profile and Preferences
The main body of this page is the user Session self-service surface: after Java / Python / Go load a Session via a user-mode client, they call the same-named Account methods isomorphically; REST replays the Session Cookie issued at sign-in.
- Web (user session)
- Java
- Python
- Go
- REST (curl)
const me = await account.get(); // Throws 401 when not logged in; treat as not logged in and redirect to login
await account.updateName({ name: '新昵称' });
await account.updatePassword({ newPassword: '<new-password>', oldPassword: '<old-password>' });
await account.updatePrefs({ theme: 'dark', lang: 'zh-CN' }); // Merge write; explicitly set null to clear a key
const prefs = await account.getPrefs();// User-state client with a loaded Session; isomorphic calls (positional parameters match the source)
account.updateName("新昵称");
account.updatePassword("<new-password>", "<old-password>"); // Signature is (password, oldPassword)
account.updatePrefs(Map.of("theme", "dark", "lang", "zh-CN"));
Object prefs = account.getPrefs();# User-side client with Session loaded enables isomorphic calls (snake_case)
account.update_name(name='新昵称')
account.update_password(password='<new-password>', old_password='<old-password>') # Parameter names are password / old_password
account.update_prefs({'theme': 'dark', 'lang': 'zh-CN'})
prefs = account.get_prefs()account := agentbase.NewAccount(cl) // User-state client: agentbase.NewClient(agentbase.WithSession(secret), ...) to load the Session
_, _ = account.Get() // Throws 401 when not logged in; treat as not logged in and redirect to login
_, _ = account.UpdateName("新昵称")
_, _ = account.UpdatePassword("<new-password>",
account.WithUpdatePasswordOldPassword("<old-password>"))
_, _ = account.UpdatePrefs(map[string]interface{}{"theme": "dark", "lang": "zh-CN"}) // Merge write; explicitly set null to clear a key
prefs, err := account.GetPrefs()# $APPBASE_ENDPOINT contains /v1; all requests below replay the Session Cookie issued at login
curl -sS -b cookies.txt "$APPBASE_ENDPOINT/account" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID"
curl -sS -b cookies.txt -X PATCH "$APPBASE_ENDPOINT/account/name" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-d '{"name":"新昵称"}'
curl -sS -b cookies.txt -X PATCH "$APPBASE_ENDPOINT/account/password" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-d '{"password":"<new-password>","oldPassword":"<old-password>"}'
# Email: PATCH /account/email (body: email, password?)Session Management
sessionId Use 'current' for the current session; REST replays the Session Cookie.
- Web (user session)
- Java
- Python
- Go
- REST (curl)
const sessions = await account.listSessions(); // All active sessions (including the current one)
await account.updateSession('current'); // Refresh a specified session
await account.deleteSession('current'); // Logs out the current device only
await account.deleteSessions(); // Logs out the current session as well// User-state client with a loaded Session; the current session's sessionId uses "current"
Object sessions = account.listSessions();
account.updateSession("current");
account.deleteSession("current");
account.deleteSessions();# User-side client loads Session (snake_case)
sessions = account.list_sessions()
account.update_session(session_id='current')
account.delete_session('current')
account.delete_sessions()sessions, err := account.ListSessions() // All active sessions (including the current one)
_, _ = account.UpdateSession("current") // Refresh a specified session
_, _ = account.DeleteSession("current") // Logs out the current device only
_, _ = account.DeleteSessions() // Logs out the current session as wellcurl -sS -b cookies.txt "$APPBASE_ENDPOINT/account/sessions" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID"
curl -sS -b cookies.txt -X PATCH "$APPBASE_ENDPOINT/account/sessions/current" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID"
curl -sS -b cookies.txt -X DELETE "$APPBASE_ENDPOINT/account/sessions/current" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID"
curl -sS -b cookies.txt -X DELETE "$APPBASE_ENDPOINT/account/sessions" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID"Login Logs
listLogs audits sign-ins and sensitive operations; REST endpoints are not listed in the API reference, use the SDK.
- Web (user session)
- Java
- Python
- Go
const logs = await account.listLogs(); // queries supports pagination/filteringvar logs = account.listLogs(null, null); // Signature: listLogs(queries, total)logs = account.list_logs()logs, err := account.ListLogs() // queries supports pagination/filteringPush Targets
createPushTarget / updatePushTarget / deletePushTarget maintain message push destinations (used together with Messaging); REST endpoints are not listed in the API reference, use the SDK.
- Web (user session)
- Java
- Python
- Go
await account.createPushTarget({ targetId: ID.unique(), providerId: '<providerId>', identifier: '<device-token>' });
await account.updatePushTarget({ targetId: '<targetId>', identifier: '<device-token>' });
await account.deletePushTarget({ targetId: '<targetId>' });import io.agentbase.ID;
// PushTarget methods are in console-java's io.agentbase.console.services.Account
// (Account in server-java.7.0 has no create/update/deletePushTarget);
// The API path /account/targets/push is user-scoped; parameters are ordered targetId, identifier, providerId (providerId comes last)
account.createPushTarget(ID.unique(), "<device-token>", "<providerId>");
account.updatePushTarget("<targetId>", "<device-token>");
account.deletePushTarget("<targetId>");# Account in server-python@release-2.6.0 has no push target methods
# (create_push_target / update_push_target / delete_push_target);
# This operation uses the Web SDK.// server-go@release-2.6.0: the account package has no PushTarget methods; use the Web SDK for this operation.Identities
listIdentities views bound OAuth/external identities, deleteIdentity unlinks; before unlinking the last identity, confirm that a usable sign-in method remains. REST endpoints are not listed in the API reference, use the SDK.
- Web (user session)
- Java
- Python
- Go
const identities = await account.listIdentities();
await account.deleteIdentity({ identityId: '<identityId>' });var identities = account.listIdentities(null, null); // Signature: listIdentities(queries, total)
account.deleteIdentity("<identityId>");identities = account.list_identities()
account.delete_identity(identity_id='<identityId>')identities, err := account.ListIdentities()
_, _ = account.DeleteIdentity("<identityId>") // Before unlinking the last identity, confirm another usable login method remains to avoid locking the accountVerification and Password Recovery
Email/phone verification and password recovery are both two steps: "initiate → confirm on the email/SMS callback page with userId + secret"; REST endpoints are not listed in the API reference, use the SDK.
- Web (user session)
- Java
- Python
- Go
// Email verification; phone corresponds to createPhoneVerification / updatePhoneVerification
await account.createEmailVerification('https://example.com/verify');
await account.updateEmailVerification({ userId: '<userId>', secret: '<secret>' });
// Password recovery: set the new password directly on the callback page
await account.createRecovery('https://example.com/recovery');
await account.updateRecovery({ userId: '<userId>', secret: '<secret>', password: '<new-password>' });// Email verification; phone corresponds to createPhoneVerification / updatePhoneVerification
account.createEmailVerification("https://example.com/verify");
account.updateEmailVerification("<userId>", "<secret>");
// Password recovery: set the new password directly on the callback page
account.createRecovery("user@example.com", "https://example.com/recovery"); // Signature is (email, url)
account.updateRecovery("<userId>", "<secret>", "<new-password>");# Email verification; for phone see create_phone_verification / update_phone_verification
account.create_email_verification(url='https://example.com/verify')
account.update_email_verification(user_id='<userId>', secret='<secret>')
# Password recovery: set the new password directly on the callback page
account.create_recovery(email='user@example.com', url='https://example.com/recovery') # Signature is (email, url)
account.update_recovery(user_id='<userId>', secret='<secret>', password='<new-password>')// Email verification; phone corresponds to CreatePhoneVerification / UpdatePhoneVerification
_, _ = account.CreateEmailVerification("https://example.com/verify")
_, _ = account.UpdateEmailVerification("<userId>", "<secret>")
// Password recovery: issued via Recovery email; CreateRecovery takes Email + Url; the callback page directly sets the new password
_, _ = account.CreateRecovery("user@example.com", "https://example.com/recovery")
_, _ = account.UpdateRecovery("<userId>", "<secret>", "<new-password>")Account Usage (2.6.0)
getUsageAggregates returns aggregations of four standard Meters for the current account's last 30 UTC days; the time window is fixed and intervals cannot be chosen. REST endpoints are not listed in the API reference, use the SDK.
- Web (user session)
- Java
- Python
- Go
const usage = await account.getUsageAggregates(); // quantity: null means missing and must not be displayed as 0var usage = account.getUsageAggregates(); // Returns io.agentbase.models.MeterUsageList# Account in server-python@release-2.6.0 has no get_usage_aggregates
# (/account/usage/aggregates method is missing); this operation goes through the Web SDK.// server-go@release-2.6.0: Account has no GetUsageAggregates; use the Web SDK for this operation.Example Guide
Examples for each language are centralized in the language tree
examples/; for React Hook combos (useAuth:account.get+deleteSession('current')) see authentication.md sign-in methods andskills/ob-agentbase/references/client-sdks/web.md"Authentication API".