Docs
Contents

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

Usage workflow

  1. Read the current account: account.get(); throws 401 when not signed in, and the frontend proceeds with the sign-in flow accordingly.

  2. Modify profile: updateName / updateEmail (requiring password depending on the scenario) / updatePhone / updatePassword (requires old credential verification).

  3. 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.

  4. Session management: account.listSessions to list all active sessions (including the current one), account.getSession to query a single one, account.updateSession to refresh a specified session, account.deleteSessions to sign out of all, account.deleteSession('current') to sign out of the current one.

  5. Login logs: account.listLogs to audit sign-ins and sensitive operations.

  6. Push targets: createPushTarget / updatePushTarget / deletePushTarget to maintain message push destinations (used together with Messaging).

  7. Identities: account.listIdentities to view bound OAuth/external identities, account.deleteIdentity to unlink.

  8. Email/phone verification: account.createEmailVerification(url) → the email confirmation callback calls account.updateEmailVerification({ userId, secret }); Phone corresponds to createPhoneVerification / updatePhoneVerification.

  9. Password recovery: account.createRecovery(url) → account.updateRecovery({ userId, secret, password }).

  10. 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 carrying quantity/complete/freshnessAt/reason; quantity: null means missing and must not be displayed as 0.

Key parameters and returns

CallKey parametersReturns
get / updateNamename (optional)Models.User ($id, email, name, labels, prefs, etc.)
updateEmail / updatePhoneemail|phone, password (optional)User (when converting an anonymous account, password is the new password)
updatePasswordnewPassword, oldPassword (optional)User
updatePrefsArbitrary key-value object (merge semantics)User
listSessions / getSession / updateSession / deleteSession(s)sessionId (use 'current' for the current session)Session list / Session
listLogsqueries (optional; pagination/filtering)Log list
createPushTarget etc.targetId, providerId, identifierPushTarget
getUsageAggregates (2.6.0)None (fixed to the last 30 UTC days, range: '30d')MeterUsageList (four Meters, coverage, freshness)

Errors and boundaries

SDK Category Differences

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.

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();

Session Management

sessionId Use 'current' for the current session; REST replays the Session Cookie.

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

Login Logs

listLogs audits sign-ins and sensitive operations; REST endpoints are not listed in the API reference, use the SDK.

const logs = await account.listLogs();   // queries supports pagination/filtering

Push Targets

createPushTarget / updatePushTarget / deletePushTarget maintain message push destinations (used together with Messaging); REST endpoints are not listed in the API reference, use the SDK.

await account.createPushTarget({ targetId: ID.unique(), providerId: '<providerId>', identifier: '<device-token>' });
await account.updatePushTarget({ targetId: '<targetId>', identifier: '<device-token>' });
await account.deletePushTarget({ targetId: '<targetId>' });

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.

const identities = await account.listIdentities();
await account.deleteIdentity({ identityId: '<identityId>' });

Verification 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.

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

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.

const usage = await account.getUsageAggregates();   // quantity: null means missing and must not be displayed as 0

Example Guide