Modifying a 2FA Message

ImportantIdentity Cloud's 2FA feature is currently in Limited Availability. Please contact your Akamai representative as usage of 2FA features must be approved during Limited Availability.


By default, each time a user goes through two-factor authenticatio, that user receives a message similar to the following, a message sent either by SMS text messaging or by email:

Akamai Documentation: Your secure access code is 060389. Do not share this code with anyone. Akamai Documentation will never ask you for it.


Note. In your messages, the text marked in red will be replaced by the name of your site and the actual access code sent to the user.


If you like this default wording, no problem: just leave the message text exactly as it is. And if you don’t like the default wording? Again, no problem; in this section of the documentation, we’ll walk you through the process of changing your 2FA message text. 


Before we do that, however, let’s take a closer look at a (color-coded) version of the secondFactor message:


{

    "sms": "{{site_name}}: Your secure access code is {{code}}. Do not share this code with anyone. {{site_name}} will never ask you for it.",

    "email": {

        "subject": "{{site_name}}One Time Code",

        "textBody": "{{site_name}}: Your secure access code is {{code}}. Do not share this code with anyone.{{site_name}} will never ask you for it.",

        "htmlBody": "<p>{{site_name}}: Your secure access code is {{code}}. Do not share this code with anyone.{{site_name}}will never ask you for it.</p>"

    },

    "_self": "/config/79y4mqf2rt3bxs378kw5479xdu/flows/moreJTL/locales/en-US/2faMessages/secondFactor"

}


The color coding is explained in the following table:


Text Color

Description

green

Property names for the message. Don’t change these names, and don’t delete any of them.


red

Message sent to users. This text can be edited, supplemented, or deleted as needed. 


blue

JTL (Janrain Templating Language) tags that function as variables in your messages. 2FA messages support two (and only two) JTL tags:


  • {{site_name}}. The name of your website. The value for this tag is taken from the site_name setting in your application client. If you don’t like this, that’s fine: {{site_name}} can safely be removed from your 2FA messages.

  • {{code}}. The access code generated by Hosted Login and sent to the user. Whatever else you do, don’t remove {{code}} from your messages. If you do, the user won’t know the access code that he or she is expected to supply in order to log in.


orange

HTML tags. You can use HTML tags and inline CSS formatting to style your 2FA messages. (See Formatting HML emails by using CSS for some examples.)


purple

Pointer to the 2FA message. When you copy the API response and paste it into your new API call you can either leave the _­self property in or delete it: it makes no difference. (Just don’t try to change the path in any way.)



So how you modify the text of a 2FA message? We recommend that you do it like this:


First, use the /config/{app}/flows/{flow}/locales/{locale}/2faMessages/{message} endpoint and the GET method to return the current properties and property values of the message. Copy those property and property values, then use that same endpoint and the PUT method to create a second API call. Paste the copied information into the body parameter of this new API call, and then start to edit the message text. For example, here we’ve made changes to pretty much everything, including the SMS message, the email subject line, and the plain-text and HTML email text:


{
    "sms": "Here's your access code for the {{site_name}} site: {{code}}.",
    "email": {
        "subject": "{{site_name}} Access Code",
        "textBody": "Here's your access code for the {{site_name}} site: {{code}}.",
        "htmlBody": "<p>Here's your access code for the {{site_name}} site: {{code}}.</p>"
    }
}


Note that there’s no requirement that the text for your three message types – SMS, plain-text, and HTML – be identical. Consistency is usually better than inconsistency, but if there’s a good reason to word the SMS message different than you word the plain-text email message, well, have at it.


After making our changes, we’ll end up with an API call that looks similar to this:


curl -L -X PUT \
  'https://v1.api.us.janrain.com/config/79y4mqf2rt3bxs378kw5479xdu/flows/moreJTL/
locales/en-US/2faMessages/secondFactor' \
  -H 'Authorization: Basic eTR4Zmc2ZjQ0bXNhYzN2ZXBqanZ4Z2d6dnQzZTNzazk6OTVjY3hrN2
N6YnZ1eng2ZHB0ZTVrOXA2ZGo1Ynpla3U=' \
  -H 'Content-Type: application/json' \
  -d '{
    "sms": "Here's your access code for the {{site_name}} site: {{code}}.",
    "email": {
      "subject": "{{site_name}} Access Code",
      "textBody": "Here's your access code for the {{site_name}} site: {{code}}.",
      "htmlBody": "<p>Here's your access code for the {{site_name}} site: {{code}}.</p>"
    }
}'


Now all we have to do is make the API call, and we’ll update the secondFactor message. After we do that the, from this point on, any time your users go through two-factor authentication their access code email will look more like this:



It’s that easy.


See Also