Modify a 2FA message

Each time a user goes through two-factor authentication, 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.


📘

Of course, in your messages, you'll see 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 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"
}

Here's a brief overview of what you're looking at:

ItemDescription
Property names for the message (like sms and email)Don’t change these names, and don’t delete any of them.
Message text (like One Time Code)This text can be edited, modified, or deleted as needed.
JTL (Janrain Templating Language) tags2FA 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.
HTML tagsYou can use HTML tags and inline CSS formatting to style your 2FA messages. (See Format 2FA emails by using CSS for some examples.)
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 do 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 the 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 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 update the secondFactor message. After we do that then any time your users go through two-factor authentication their access code email will look more like this:

It’s that easy.