Instructions for

Change your primary email address

Enable users to change their primary email address in a password-optional app.

Learning outcomes

Integrate the change primary email flow into your SPA app.

What you need

Sample code

Overview

Allowing a user to change their primary email is a critical task when they only use their username and email address to sign in to your app. Much like a password, a user must be able to change their email address, especially if it becomes compromised. With the Okta Auth Javascript SDK (opens new window) you can enable your users to change their primary emails in your app.

The SDK contains a series of methods (opens new window) that update the user's primary email address and other profile information. These methods are secure and can be safely used in browser-based SPA apps. In this guide, you learn how to use these methods to integrate the change email functionality in your app.

Note: These SDK methods use the MyAccount API (opens new window) to update the user's profile information.

Update configurations

Set up your Okta org for a password-optional use case
To test the email change flow, set up a user with an enrolled email authenticator.

Integrate

Summary of steps

The following summarizes the steps involved when a user changes their primary email address.

1. The user signs in to your app

The user signs in to your app before they can change their primary email address. During the sign-in flow create an OktaAuth object, which is required to authenticate the user and later change their email.

const oktaAuth = (() => {
  return new OktaAuth(oidcConfig);
})();

To learn more about initializing this object and how to integrate the user sign in, see Example Client (opens new window) in Okta Auth Javascript SDK's readme.

2. The user starts the change primary email flow

The user starts the change primary email flow by clicking an Edit link next to the Primary Email Address field. Add an Edit link that gives the user an entry point to change their email.

Screenshot showing an edit link next to the primary email address.

3. The user submits a new primary email

When the user clicks the Edit link, display a dialog for the user to submit their new email address.

Screenshot showing a page with a new primary email input field and continue button.

When the user clicks Continue and submits their new email address, create an object of type AddEmailPayload (opens new window) and set

profile.email to the new primary email.
role to PRIMARY, which identifies the email as the primary email address.
sendEmail to true, which sends an email challenge to the newly added email. The default is true.

const addEmailPayload = {
    "profile":{
       "email":"john.doe.new@example.com"
    },
    "sendEmail":true,
    "role":"PRIMARY"
 };

Call addEmail() (opens new window) and pass in the new AddEmailPayload object.

import {
  addEmail
} from '@okta/okta-auth-js/myaccount';

const handleAddEmail = async (role, email) => {
  return addEmail(oktaAuth, {
    addEmailPayload
  });
};

Note: If you want to send the email challenge in a separate step, setsendEmail=false and call sendEmailChallenge() (opens new window) after addEmail() (opens new window).

4. Identity Engine requests new email verification

addEmail() (opens new window) returns an EmailTransaction (opens new window) object. The object has a status of UNVERIFIED that indicates that the user needs to verify their identity with the new email.

{
   "id":"2e355d8376d4a12bb45ed54ebf8dd4d5",
   "status":"UNVERIFIED",
   "profile":{
      "email":"john.doe.new@example.com"
   },
   "roles":[
      "PRIMARY"
   ],
}

Build the logic that handles this response and sends the user to a dialog where they enter the OTP.

5. The user verifies their identity with the new email

The user opens the email sent by Identity Engine and copies the one-time passcode (OTP) to your app. Create a dialog to allow the user to enter and submit the OTP.

Screenshot showing a page with an OTP input field and continue button.

When the user submits the OTP, create an object of type VerificationPayload (opens new window) and set verificationCode to the OTP entered by the user.

const verificationPayload = {
    "verificationCode":"197277"
 };

Call verify() (opens new window) on the EmailTransaction returned from the previous step and pass in the new VerificationPayload object. Wrap the method call in a try...catch statement to catch invalid OTPs and other API exceptions raised from EmailTransaction.verify().

...
try {
  if (transaction.status === 'UNVERIFIED') {
    if (transaction.verify) {
      await transaction.verify(verificationPayload);
    }
  }
} catch (err) {
  if (err.errorSummary === 'insufficient_authentication_context') {
    onFinish();
    startReAuthentication(err);
  } else {
    setError(err);
  }
}
...

6. Your app handles a successful identity verification

When the OTP is valid and the email change completes successfully, EmailTransaction.verify() returns no data and completes without exception. Your app should close the change email dialog, refresh the main page, and display the new primary email and any other profile information.

On this page

Change your primary email address