Guide
TrainingSupportCommunity

View 2FA messages

Suggest Edits

To view your two-factor authentication (2FA) messages , use the GET method and call the [/config/{app}/flows/{flow}/locales/{locale}/2faMessages](List your 2FA messages
GET) operation. 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 includes 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 included in the flow after all. In that case, you can use the /config/{appId}/flows/{flow}/2faMessages operation to add those messages].


To return detailed information for a specific message, tack the message name on the end of the operation 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.


📘

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 discuss those items in the article Modify a 2FA message.

If you’ve localized your 2FA messages you can view your message translations by replacing en-US with 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 the secondFactor messages into Spanish. As a result, there’s nothing for the /config/{app}/flows/{flow}/locales/{locale}/2faMessages/{message} operation 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:


Return just the SMS message or the email subject line

When using the /config/{app}/flows/{flow}/locales/{locale}/2faMessages/{message} operation it’s 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

Updated over 2 years ago