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:

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.