Viewing Your 2FA Messages

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.


In This Document

Viewing Your 2FA Messages

When you call the /config/{appId}/flows/{flow}/2faMessages you don’t get an API response if your call succeeds; instead, you simply get the HTTP status code 204 No Content. So then how do you know if the API call really worked?

The best way to verify that the 2FA messages have been added to a flow is to use the GET method to call the /config/{app}/flows/{flow}/locales/{locale}/2faMessages endpoint. For example, this API call returns all the 2FA messages found in the moreJTL flow:


curl -L -X GET \
 'https://v1.api.us.janrain.com/config/79y4mqf2rt3bxs378kw5479xdu/flows/moreJTL/
locales/en-US/2faMessages' \ 
  - H 'Authorization: Basic eTR4Zmc2ZjQ0bXNhYzN2ZXBqanZ4Z2d6dnQzZTNzazk6OTVjY3hrN2N6
YnZ1eng2ZHB0ZTVrOXA2ZGo1Ynpla3U='


If your flow does include the 2FA messages you’ll get back a response similar to this:


[
    {
        "_self": "/config/79y4mqf2rt3bxs378kw5479xdu/flows/moreJTL/locales/en-US/
2faMessages/secondFactor",
        "name": "secondFactor"
    },
    {
        "_self": "/config/79y4mqf2rt3bxs378kw5479xdu/flows/moreJTL/locales/en-US/
2faMessages/resendVerification",
        "name": "resendVerification"
    },
    {
        "_self": "/config/79y4mqf2rt3bxs378kw5479xdu/flows/moreJTL/locales/en-US/
2faMessages/registrationVerification",
        "name": "registrationVerification"
    }
]


If you get an HTTP status code of 404 Not Found that means that the 2FA messages aren’t in the flow after all. In that case, you can use the /config/{appId}/flows/{flow}/2faMessages endpoint to add those messages.


Note. Due to a prerelease bug, it’s possible that won’t get a 404 error if the messages don’t exist in the flow; instead, you’ll get an API response suggesting that the messages are in the flow when they really aren’t. This problem should be fixed soon.


To return detailed information for a specific message, tack the message name on the end of the endpoint URL. For example, this call returns information only for the secondFactor message:


curl -L -X GET \
 'https://v1.api.us.janrain.com/config/79y4mqf2rt3bxs378kw5479xdu/flows/moreJTL/
locales/en-US/2faMessages/secondFactor' \ 
  - H 'Authorization: Basic eTR4Zmc2ZjQ0bXNhYzN2ZXBqanZ4Z2d6dnQzZTNzazk6OTVjY3hrN2
N6YnZ1eng2ZHB0ZTVrOXA2ZGo1Ynpla3U='


The returned information will look similar to this:


    "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"
}


This is a good time to point out that each 2FA message actually consists of three separate messages. First, there’s the text message sent to a user’s mobile device. In the preceding API response, the actual message sent to a mobile device is the value of the sms property.


Second, we have two types of email messages: plain-text (textBody) and HTML (htmlBody). As the names imply, the HTML email allows you to use HTML tags and CSS when constructing the message; the plain-text message is, well, plain text.


By the way, even though we have two different types of email messages, we only have one subject line (subject). Because you can’t format subject lines, plain-text emails and HTML emails use the same subject line.


Note. Why two different emails? That’s because some email clients are configured to accept only plain-text emails. When we send a 2FA email to a user, we actually send both a plain-text version and an HTML version. It’s then up to the email client to decide which version to display to the user.


And yes, there are some other things in that API response, things like {{site_name}} and {{code}}. We’ll talk about those items when we talk about modifying messages.


If you’ve localized your 2FA messages you can view those message translations simply by replacing en-USwith the appropriate locale. For example, this command returns the French (fr-FR) version of the secondFactor message:


curl -L -X GET \
 'https://v1.api.us.janrain.com/config/79y4mqf2rt3bxs378kw5479xdu/flows/moreJTL/
locales/fr-FR/2faMessages/secondFactor' \ 
  - H 'Authorization: Basic eTR4Zmc2ZjQ0bXNhYzN2ZXBqanZ4Z2d6dnQzZTNzazk6OTVjY3hrN2N
6YnZ1eng2ZHB0ZTVrOXA2ZGo1Ynpla3U='


That French version looks (in our case, at least) like this:


{
    "email": {
        "subject": "{{site_name}} Code temporel",
        "textBody": "{{site_name}}: Votre code d'accès sécurisé est {{code}}.",
        "htmlBody": "<p>{{site_name}}: Votre code d'accès sécurisé est {{code}}.</p>"
    },
    "sms": "{{site_name}}: Votre code d'accès sécurisé est {{code}}.",
    "_self": "/config/79y4mqf2rt3bxs378kw5479xdu/flows/moreJTL/locales/fr-FR/
2faMessages/secondFactor"
}


We should also point out that, when looking at localized messages, you might get a response similar to the following. For example, in our test implementation of Hosted Login v2 this is the Spanish (es-ES) version of the secondFactor message:


{
    "sms": "",
    "email": {
        "subject": "",
        "textBody": "",
        "htmlBody": ""
    },
    "_self": "/config/79y4mqf2rt3bxs378kw5479xdu/flows/moreJTL/locales/es-ES/
2faMessages/secondFactor"
}


Why is everything blank? That’s easy: although this is a valid locale, we haven’t translated secondFactorinto Spanish. As a result, there’s nothing for the /config/{app}/flows/{flow}/locales/{locale}/2faMessages/{message} endpoint to show. 

By comparison, suppose you look at messages that use Faroese (fo), a locale that doesn’t exist in your flow. In that case, the API call fails with the following error:


Returning Just the SMS Message or  the Email Subject Line

Return to top


When using the /config/{app}/flows/{flow}/locales/{locale}/2faMessages/{message} endpoint it’s also possible to return just the SMS message or just the email subject line. (At the moment, it’s not possible to return just the email text, in either HTML or plain-text format). To return just the SMS message, use this command:


curl -L -X GET \
  'https://v1.api.us.janrain.com/config/79y4mqf2rt3bxs378kw5479xdu/flows/moreJTL/
locales/en-US/2faMessages/secondFactor/sms' \ 
  -H 'Authorization: Basic eTR4Zmc2ZjQ0bXNhYzN2ZXBqanZ4Z2d6dnQzZTNzazk6OTVjY3hrN2N
6YnZ1eng2ZHB0ZTVrOXA2ZGo1Ynpla3U='


In turn, your API response will look like this:


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


To return just the email subject line, use this command:


curl -L -X GET \
  'https://v1.api.us.janrain.com/config/79y4mqf2rt3bxs378kw5479xdu/flows/moreJTL/
locales/en-US/2faMessages/secondFactor/email/subject' \ 
  -H 'Authorization: Basic eTR4Zmc2ZjQ0bXNhYzN2ZXBqanZ4Z2d6dnQzZTNzazk6OTVjY3hrN2N6
YnZ1eng2ZHB0ZTVrOXA2ZGo1Ynpla3U='


As you might expect, that brings back just the email subject line:


{{site_name}} One Time Code




See Also