Example: Change User Email

This example goes through the steps for a user to change his/her own email address.

This exercise assumes that:

• You have a valid login for the Akana API Platform.
• The platform's security settings are configured to allow users to change their own email addresses. If you're not sure, check the security settings (GET /api/businesses/{BusinessID}/securitysettings) to make sure that UserModifyEmail is set to com.soa.feature.enabled. If this setting is disabled, users cannot change their own email addresses.
• You have a second email account that isn't linked to a platform account, and can access it immediately to retrieve the notification email.

Follow the instructions below.

To change the email address for your account on the Akana API Platform using the API

1. Log in via the API, POST /api/login operation, using your own email and password in the body of the operation instead of the placeholder values given below.
   • HTTP method: POST
   • URL: https://{hostname}/api/login
   • Accept header: application/json
   • Content-Type header: application/json
   • Request Body:

     {
       "email":"myemailaddress.com",
       "password":"MyPassword"
     }

   The platform API returns the login cookie, which you'll need to send with the request headers for any operation that requires login, and the CSRF cookie, which you'll need to use to put together the CSRF header if required by platform settings (not covered in this exercise: see Example: Using the CSRF header).

2. Request a change of email address for your account, using the POST /api/users/{UserID}/sendEmailChangeCode operation. In your API call, use the request body as shown below. Fill in valid values for yourself (UserID in the URL, email address in the request body).
   • HTTP method: POST
   • URL: https://{hostname}/api/users/{UserID}/sendEmailChangeCode

     Note: Your UserID is the userFDN in the response to the login operation.

   • Accept header: application/json
   • Content-Type header: application/x-www-form-urlencoded
   • Cookie header.
   • CSRF header: include it if needed. If you are not sure whether it's needed or not, refer to CSRF Prevention on the Platform.
   • Request Body:

     newEmailAddress=mynewemailaddress.com

     Note: The new email address must be a valid address that you have immediate access to so that you can retrieve the notification message that the platform sends, with the confirmation code.

3. Check your new email address to get the notification email. The platform sends out two notifications:
   • One to the new email address, with the confirmation code, which you'll use for the next operation. Make sure you get the full code, without any leading or trailing spaces.
   • One to the old email address, as a security measure.
4. Confirm the change of email address for your account, using the POST /api/users/validateEmailChangeCode operation. In the body, provide the values for both parameters: the confirmation code from the notification email, and the new email address.
   • HTTP method: POST
   • URL: https://{hostname}/api/users/api/users/validateEmailChangeCode
   • Accept header: application/json
   • Content-Type header: application/json
   • Cookie header.
   • CSRF header: include it if needed. If you are not sure whether it's needed or not, refer to CSRF Prevention on the Platform.
   • Request Body:

     {
       "changeCode":"9Jg0L9gkvAgz5iZrhSKH60upIct72sO9aX0ifzAwYem3g6_Gd39SBlDysG7rlfGOK2H_4OkeVZEDaUT-dh31h0-2D8NDffW4SbCwXJ_3oc5LYDOcCI0R-RPfTwKMBGavKETyQt41hOsa5w6dH5dZyCcIEhcmztkuc-m5i0",
       "newEmailAddress":"mynewemailaddress.com"
     }

5. When done, remember to log out using the GET /api/login/endsession operation. Use the following values:
   • URL: https://{hostname}/api/login/endsession
   • Accept header: application/json

Note: Next time you log in, remember to use the new email address.

Related Topics