or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

authentication.mddevice-management.mdindex.mdmfa.mdsession-management.mdstorage.mduser-attributes.mduser-management.mduser-pool.md
tile.json

user-management.mddocs/

User Management

Comprehensive user operations including registration, confirmation, password management, and account control.

Capabilities

User Registration and Confirmation

User registration flow including confirmation and resending confirmation codes.

/**
 * Confirms user registration with verification code
 * @param code - Verification code sent to user's email/phone
 * @param forceAliasCreation - Whether to force creation of alias
 * @param callback - Callback function to handle the result
 * @param clientMetadata - Optional client metadata for Lambda triggers
 */
confirmRegistration(
  code: string,
  forceAliasCreation: boolean,
  callback: NodeCallback<any, any>,
  clientMetadata?: ClientMetadata
): void;

/**
 * Resends the confirmation code to user's registered email/phone
 * @param callback - Callback function to handle the result
 * @param clientMetadata - Optional client metadata for Lambda triggers
 */
resendConfirmationCode(
  callback: NodeCallback<Error, any>,
  clientMetadata?: ClientMetadata
): void;

Usage Examples:

import { CognitoUser } from "amazon-cognito-identity-js";

// Confirm user registration
cognitoUser.confirmRegistration("123456", false, (err, result) => {
  if (err) {
    console.error("Confirmation failed:", err.message);
    return;
  }
  console.log("User confirmed successfully:", result);
});

// Resend confirmation code
cognitoUser.resendConfirmationCode((err, result) => {
  if (err) {
    console.error("Resend failed:", err.message);
    return;
  }
  console.log("Confirmation code resent:", result);
});

Password Management

Complete password management including change password and forgot password flows.

/**
 * Changes user's password (requires current password)
 * @param oldPassword - User's current password
 * @param newPassword - New password to set
 * @param callback - Callback function to handle the result
 * @param clientMetadata - Optional client metadata for Lambda triggers
 */
changePassword(
  oldPassword: string,
  newPassword: string,
  callback: NodeCallback<Error, 'SUCCESS'>,
  clientMetadata?: ClientMetadata
): void;

/**
 * Initiates forgot password flow
 * @param callbacks - Callback handlers for different outcomes
 * @param clientMetadata - Optional client metadata for Lambda triggers
 */
forgotPassword(
  callbacks: {
    onSuccess: (data: any) => void;
    onFailure: (err: Error) => void;
    inputVerificationCode?: (data: any) => void;
  },
  clientMetadata?: ClientMetadata
): void;

/**
 * Confirms new password with verification code from forgot password flow
 * @param verificationCode - Code sent to user's email/phone
 * @param newPassword - New password to set
 * @param callbacks - Success/failure callback handlers
 * @param clientMetadata - Optional client metadata for Lambda triggers
 */
confirmPassword(
  verificationCode: string,
  newPassword: string,
  callbacks: {
    onSuccess: (success: string) => void;
    onFailure: (err: Error) => void;
  },
  clientMetadata?: ClientMetadata
): void;

Usage Examples:

// Change password (user is authenticated)
cognitoUser.changePassword(
  "OldPassword123!",
  "NewSecurePassword456!",
  (err, result) => {
    if (err) {
      console.error("Password change failed:", err.message);
      return;
    }
    console.log("Password changed successfully:", result);
  }
);

// Forgot password flow
cognitoUser.forgotPassword({
  onSuccess: (data) => {
    console.log("Forgot password initiated:", data);
  },
  onFailure: (err) => {
    console.error("Forgot password failed:", err.message);
  },
  inputVerificationCode: (data) => {
    console.log("Verification code sent:", data);
    
    // Get verification code from user and confirm new password
    const verificationCode = prompt("Enter verification code:");
    const newPassword = prompt("Enter new password:");
    
    cognitoUser.confirmPassword(
      verificationCode,
      newPassword,
      {
        onSuccess: (result) => {
          console.log("Password reset successful:", result);
        },
        onFailure: (err) => {
          console.error("Password reset failed:", err.message);
        }
      }
    );
  }
});

Account Management

User account operations including deletion and data retrieval.

/**
 * Deletes the user account permanently
 * @param callback - Callback function to handle the result
 */
deleteUser(callback: NodeCallback<Error, string>): void;

/**
 * Gets comprehensive user data including MFA settings and preferences
 * @param callback - Callback function to handle the result
 * @param params - Optional parameters for the request
 */
getUserData(
  callback: NodeCallback<Error, UserData>,
  params?: any
): void;

interface UserData {
  /** Available MFA options for the user */
  MFAOptions: MFAOption[];
  /** User's preferred MFA setting */
  PreferredMfaSetting: string;
  /** Array of user attributes */
  UserAttributes: ICognitoUserAttributeData[];
  /** List of MFA settings configured for user */
  UserMFASettingList: string[];
  /** Username */
  Username: string;
}

interface MFAOption {
  /** Delivery medium for MFA (SMS or EMAIL) */
  DeliveryMedium: 'SMS' | 'EMAIL';
  /** Attribute name used for MFA delivery */
  AttributeName: string;
}

Usage Examples:

// Delete user account
cognitoUser.deleteUser((err, result) => {
  if (err) {
    console.error("Delete user failed:", err.message);
    return;
  }
  console.log("User deleted successfully:", result);
});

// Get comprehensive user data
cognitoUser.getUserData((err, userData) => {
  if (err) {
    console.error("Get user data failed:", err.message);
    return;
  }
  
  console.log("Username:", userData.Username);
  console.log("MFA Options:", userData.MFAOptions);
  console.log("Preferred MFA:", userData.PreferredMfaSetting);
  console.log("User Attributes:", userData.UserAttributes);
  console.log("MFA Settings:", userData.UserMFASettingList);
});

User Information

Basic user information retrieval methods.

/**
 * Gets the username for this user
 * @returns The username string
 */
getUsername(): string;

/**
 * Gets the current sign-in user session
 * @returns Current session or null if not signed in
 */
getSignInUserSession(): CognitoUserSession | null;

/**
 * Sets the user session manually
 * @param signInUserSession - Session to set for the user
 */
setSignInUserSession(signInUserSession: CognitoUserSession): void;

Usage Examples:

// Get basic user info
const username = cognitoUser.getUsername();
console.log("Username:", username);

// Check current session
const currentSession = cognitoUser.getSignInUserSession();
if (currentSession && currentSession.isValid()) {
  console.log("User has valid session");
} else {
  console.log("No valid session found");
}

// Set session manually (after authentication)
cognitoUser.setSignInUserSession(newSession);

Validation and Error Handling

Common validation requirements and error scenarios for user management operations.

Password Requirements:

  • Password policies are configured at the User Pool level
  • Common requirements include minimum length, character types, etc.
  • Password validation errors include specific requirement violations

Confirmation Code Requirements:

  • Codes are typically 6-digit numeric values
  • Codes have expiration times (configurable in User Pool)
  • Limited number of attempts before lockout

Common Error Codes:

  • CodeMismatchException - Invalid confirmation code
  • ExpiredCodeException - Confirmation code expired
  • InvalidPasswordException - Password doesn't meet requirements
  • LimitExceededException - Too many attempts
  • UserNotFoundException - User doesn't exist
  • UserNotConfirmedException - User account not confirmed

Error Handling Example:

cognitoUser.confirmRegistration(code, false, (err, result) => {
  if (err) {
    switch (err.code) {
      case 'CodeMismatchException':
        console.error("Invalid confirmation code");
        break;
      case 'ExpiredCodeException':
        console.error("Confirmation code expired");
        // Offer to resend code
        break;
      case 'UserNotFoundException':
        console.error("User not found");
        break;
      default:
        console.error("Confirmation error:", err.message);
    }
    return;
  }
  console.log("Confirmation successful");
});

Advanced User Management

Additional user management capabilities for complex scenarios.

Cache Management:

/**
 * Gets cached device key and password for device authentication
 */
getCachedDeviceKeyAndPassword(): void;

Client Metadata Usage: Client metadata is passed to AWS Lambda triggers and can be used for:

  • Custom business logic in triggers
  • Tracking authentication sources
  • Passing additional context to custom workflows
const clientMetadata = {
  source: "mobile-app",
  version: "1.2.3",
  platform: "ios"
};

cognitoUser.changePassword(oldPass, newPass, callback, clientMetadata);