Manage user attributes
User attributes such as email address, phone number help you identify individual users. Defining the user attributes you include for your user profiles makes user data easy to manage at scale. This information will help you personalize user journeys, tailor content, provide intuitive account control, and more. You can capture information upfront during sign-up or enable customers to update their profile after sign-up. In this section we take a closer look at working with user attributes, how to set them up and manage them.
Configure custom user attributes during sign-up
Custom attributes can be passed in with the userAttributes option of the signUp API:
Future<void> _signUp({ required String username, required String password, required String email, required String customValue,}) async { final userAttributes = { AuthUserAttributeKey.email: email, // Create and pass a custom attribute const CognitoUserAttributeKey.custom('my-custom-attribute'): customValue }; await Amplify.Auth.signUp( username: username, password: password, options: SignUpOptions( userAttributes: userAttributes, ), );}Retrieve user attributes
You can retrieve user attributes for your users to read in their profile using the fetchUserAttributes API. This helps you personalize their frontend experience as well as control what they will see.
Future<void> fetchCurrentUserAttributes() async { try { final result = await Amplify.Auth.fetchUserAttributes(); for (final element in result) { safePrint('key: ${element.userAttributeKey}; value: ${element.value}'); } } on AuthException catch (e) { safePrint('Error fetching user attributes: ${e.message}'); }}Update user attribute
You can use the updateUserAttribute API to create or update existing user attributes.
Future<void> updateUserEmail({ required String newEmail,}) async { try { final result = await Amplify.Auth.updateUserAttribute( userAttributeKey: AuthUserAttributeKey.email, value: newEmail, ); _handleUpdateUserAttributeResult(result); } on AuthException catch (e) { safePrint('Error updating user attribute: ${e.message}'); }}User attribute updates may require additional verification before they're complete. Check the
UpdateUserAttributeResult returned from Amplify.Auth.updateUserAttribute to see which next
step, if any, is required. When the update is complete, the next step will be done.
void _handleUpdateUserAttributeResult( UpdateUserAttributeResult result,) { switch (result.nextStep.updateAttributeStep) { case AuthUpdateAttributeStep.confirmAttributeWithCode: final codeDeliveryDetails = result.nextStep.codeDeliveryDetails!; _handleCodeDelivery(codeDeliveryDetails); break; case AuthUpdateAttributeStep.done: safePrint('Successfully updated attribute'); break; }}
void _handleCodeDelivery(AuthCodeDeliveryDetails codeDeliveryDetails) { safePrint( 'A confirmation code has been sent to ${codeDeliveryDetails.destination}. ' 'Please check your ${codeDeliveryDetails.deliveryMedium.name} for the code.', );}To update multiple user attributes at a time, call updateUserAttributes:
Future<void> updateUserAttributes() async { const attributes = [ AuthUserAttribute( userAttributeKey: AuthUserAttributeKey.email, value: 'email@email.com', ), AuthUserAttribute( userAttributeKey: AuthUserAttributeKey.familyName, value: 'MyFamilyName', ), ]; try { final result = await Amplify.Auth.updateUserAttributes( attributes: attributes, ); result.forEach((key, value) { switch (value.nextStep.updateAttributeStep) { case AuthUpdateAttributeStep.confirmAttributeWithCode: final destination = value.nextStep.codeDeliveryDetails?.destination; safePrint('Confirmation code sent to $destination for $key'); break; case AuthUpdateAttributeStep.done: safePrint('Update completed for $key'); break; } }); } on AuthException catch (e) { safePrint('Error updating user attributes: ${e.message}'); }}Verify user attribute
Some attributes require confirmation for the attribute update to complete. If the attribute needs to be confirmed, part of the result of the updateUserAttribute or updateUserAttributes APIs will be CONFIRM_ATTRIBUTE_WITH_CODE. A confirmation code will be sent to the delivery medium mentioned in the delivery details. When the user gets the confirmation code, you can present a UI to the user to enter the code and invoke the confirmUserAttribute API with their input:
Future<void> verifyAttributeUpdate() async { try { await Amplify.Auth.confirmUserAttribute( userAttributeKey: AuthUserAttributeKey.email, confirmationCode: '390739', ); } on AuthException catch (e) { safePrint('Error confirming attribute update: ${e.message}'); }}Send user attribute verification code
If an attribute needs to be verified while the user is authenticated, invoke the sendUserAttributeVerificationCode API as shown below:
Future<void> resendVerificationCode() async { try { final result = await Amplify.Auth.resendUserAttributeConfirmationCode( userAttributeKey: AuthUserAttributeKey.email, ); _handleCodeDelivery(result.codeDeliveryDetails); } on AuthException catch (e) { safePrint('Error resending code: ${e.message}'); }}