Skip to main content

User Management

The Sphere SDK provides comprehensive user management capabilities for retrieving user information and managing user accounts. All operations require authentication and follow mutually exclusive parameter rules.

Table of Contents​

Getting User Information​

Retrieve the current authenticated user's profile information.

import Sphere from "@stratosphere-network/wallet";

async function getUserInfo() {
  if (!sphere.auth.isAuthenticated()) {
    console.log("User must be authenticated to get user information.");
    return;
  }

  try {
    const userResponse = await sphere.auth.getUser();
    const user = userResponse.user;

    console.log("User Information:");
    console.log("User ID:", user.id);
    console.log("External ID:", user.externalId);
    console.log("Email:", user.email || "Not provided");
    console.log("Phone Number:", user.phoneNumber || "Not provided");
    console.log("Wallet Address:", user.address || "Not provided");
    console.log("Created At:", user.createdAt);
    console.log("Updated At:", user.updatedAt);
    console.log("Referrer:", user.referrer || "None");
    console.log("Telegram ID:", user.telegramId || "Not linked");

    return user;
  } catch (error) {
    console.error("Error fetching user information:", error);
    throw error;
  }
}

Deleting User Account​

Delete a user account using mutually exclusive authentication parameters.

⚠️ CRITICAL: Delete User Parameter Rules

Authentication parameters are MUTUALLY EXCLUSIVE:

  • ❌ NEVER provide phoneNumber + email together
  • ❌ NEVER provide phoneNumber + externalId together
  • ❌ NEVER provide email + externalId together

Choose ONE method:

  • 📱 Phone: phoneNumber + otpCode ONLY
  • 📧 Email: email + otpCode ONLY
  • 🔑 External: externalId + password ONLY

Method 1: Delete with External ID + Password​

async function deleteUserWithExternalId() {
  if (!sphere.auth.isAuthenticated()) {
    throw new Error("User must be authenticated to delete account.");
  }

  try {
    // ⚠️ Do NOT provide phoneNumber or email when using externalId
    const deleteResponse = await sphere.auth.deleteUser({
      externalId: "user@example.com",
      password: "secure-password",
      // phoneNumber: "+1234567890", // ❌ NEVER provide with externalId
      // email: "user@example.com", // ❌ NEVER provide with externalId
    });

    console.log("✅ User deleted successfully:", deleteResponse.message);

    // SDK automatically clears bearer token after deletion
    if (!sphere.auth.isAuthenticated()) {
      console.log("✅ Bearer token cleared automatically");
    }

    return deleteResponse;
  } catch (error) {
    console.error("❌ Error deleting user:", error);
    throw error;
  }
}

Method 2: Delete with Phone + OTP​

async function deleteUserWithPhone() {
  if (!sphere.auth.isAuthenticated()) {
    throw new Error("User must be authenticated to delete account.");
  }

  try {
    const phoneNumber = "+1234567890";

    // Step 1: Send OTP to phone
    await sphere.auth.sendOtp({
      phone: phoneNumber,
      // email: "user@example.com", // ❌ NEVER provide with phone
    });
    console.log("📩 OTP sent to phone for account deletion");

    // Step 2: Get OTP from user input
    const otpCodeFromUser = "123456"; // Replace with actual OTP

    // Step 3: Delete with phone + OTP ONLY
    const deleteResponse = await sphere.auth.deleteUser({
      phoneNumber: phoneNumber,
      otpCode: otpCodeFromUser,
      // email: "user@example.com", // ❌ NEVER provide with phoneNumber
      // externalId: "user123", // ❌ NEVER provide with phoneNumber
    });

    console.log("✅ User deleted successfully:", deleteResponse.message);
    return deleteResponse;
  } catch (error) {
    console.error("❌ Error deleting user with phone:", error);
    throw error;
  }
}

Method 3: Delete with Email + OTP​

async function deleteUserWithEmail() {
  if (!sphere.auth.isAuthenticated()) {
    throw new Error("User must be authenticated to delete account.");
  }

  try {
    const email = "user@example.com";

    // Step 1: Send OTP to email
    await sphere.auth.sendOtp({
      email: email,
      // phone: "+1234567890", // ❌ NEVER provide with email
    });
    console.log("📩 OTP sent to email for account deletion");

    // Step 2: Get OTP from user input
    const otpCodeFromUser = "123456"; // Replace with actual OTP

    // Step 3: Delete with email + OTP ONLY
    const deleteResponse = await sphere.auth.deleteUser({
      email: email,
      otpCode: otpCodeFromUser,
      // phoneNumber: "+1234567890", // ❌ NEVER provide with email
      // externalId: "user123", // ❌ NEVER provide with email
    });

    console.log("✅ User deleted successfully:", deleteResponse.message);
    return deleteResponse;
  } catch (error) {
    console.error("❌ Error deleting user with email:", error);
    throw error;
  }
}

Account Recovery & Password Reset​

For users who authenticate with externalId and password, the Sphere SDK provides a comprehensive recovery system. This allows users to:

  • Set up recovery methods (email and/or phone)
  • Request password resets via OTP
  • Manage their recovery options
  • Recover their account if they forget their password

📝 Note: Account recovery is only available for users who authenticate using the externalId + password method. Users authenticating with phone/email + OTP have built-in recovery through their authentication method.

Quick Example: Setting Up Recovery​

// After user registration, immediately set up recovery methods
async function setupUserRecovery(
  externalId: string,
  password: string,
  email: string,
  phone?: string
) {
  try {
    const recovery = await sphere.auth.createRecoveryMethods({
      externalId,
      password,
      emailRecovery: email,
      phoneRecovery: phone, // Optional
    });

    console.log("Recovery methods configured:", recovery);
  } catch (error) {
    console.error("Failed to set up recovery:", error);
  }
}

Quick Example: Password Reset Flow​

// Step 1: Check recovery options (public, no auth required)
const options = await sphere.auth.getRecoveryOptions("user123");
console.log("Available recovery methods:", options.recoveryOptions);

// Step 2: Request password reset
await sphere.auth.requestPasswordReset({
  externalId: "user123",
  method: "emailRecovery", // or "phoneRecovery"
});

// Step 3: Reset password with OTP
await sphere.auth.resetPassword({
  username: "user123",
  newPassword: "newSecurePassword123!",
  email: "user@example.com", // or phoneNumber for phone recovery
  otpCode: "123456",
});

For comprehensive documentation on account recovery and password reset functionality, including:

  • Complete recovery method management
  • Detailed password reset flows
  • Error handling and rate limiting
  • Best practices and security considerations

See the Account Recovery & Password Reset documentation.

Complete User Management Example​

// Complete user management workflow
async function userManagementWorkflow() {
  try {
    // Check authentication status
    if (sphere.auth.isAuthenticated()) {
      console.log("✅ User is authenticated");

      // Get user details
      const userResponse = await sphere.auth.getUser();
      console.log("👤 User info:", userResponse.user);

      // Display user profile
      const user = userResponse.user;
      console.log(`
        Profile Information:
        - ID: ${user.id}
        - External ID: ${user.externalId}
        - Email: ${user.email || "Not provided"}
        - Phone: ${user.phoneNumber || "Not provided"}
        - Address: ${user.address || "Not provided"}
        - Created: ${user.createdAt}
        - Updated: ${user.updatedAt}
        - Referrer: ${user.referrer || "None"}
        - Telegram ID: ${user.telegramId || "Not linked"}
      `);

      // User can choose to delete account if needed
      // deleteUserWithExternalId(); // Uncomment to test deletion
    } else {
      console.log("❌ User is not authenticated");
      console.log("Please authenticate first");
    }
  } catch (error) {
    console.error("Error in user management workflow:", error);
  }
}

Type Definitions​

interface User {
  id: string;
  externalId: string;
  referrer?: string;
  createdAt?: string;
  updatedAt?: string;
  email?: string;
  telegramId?: string;
  phoneNumber?: string;
  address?: string;
}

interface UserResponse {
  user: User;
}

type DeleteUserRequest =
  | {
      externalId: string;
      password: string;
      phoneNumber?: never;
      email?: never;
      otpCode?: never;
    }
  | {
      phoneNumber: string;
      otpCode: string;
      externalId?: never;
      password?: never;
      email?: never;
    }
  | {
      email: string;
      otpCode: string;
      externalId?: never;
      password?: never;
      phoneNumber?: never;
    };

interface DeleteUserResponse {
  message: string;
}

Important Notes​

  • Authentication Required: All user management operations require authentication
  • Automatic Token Clearing: deleteUser() automatically clears the bearer token
  • Same Auth Rules: User deletion follows the same mutually exclusive parameter rules as login
  • Irreversible Action: User deletion is permanent and cannot be undone
  • Data Cleanup: Deleting a user removes all associated data including wallets and transactions