Add 2FA messages to a flow

One of the major differences between Hosted Login v1 and Hosted Login v2 is the fact that the v2 version includes a sort of “primary flow” that directs much of the user interaction. For example, Hosted Login v2 includes the following two-factor authentication (2FA) screen:

The text displayed on this screen (e.g., Access Code Required) is maintained in a flow. More specifically, and in this case, the text is maintained in the JTL tag textAuthRuleSecondFactorLoginCodeHeading. However, if you look in the flow you assigned to your OIDC login client, there’s a good chance you won’t find that tag. Which is OK: if an element (such as a JTL tag) doesn’t exist, Hosted Login will (under the right circumstances) retrieve that element from the primary flow.

This is also true for your 2FA messages. By default, the text for those messages is stored only in the primary flow. Among other things, that means that you can’t modify that text; if you could, you’d be modifying the 2FA messages of everyone in the world. (Or at least everyone in the world running Hosted Login v2.)

Instead, if you want to modify (or even just look at) any of your two-factor authentication messages you first need to add these messages to your Hosted Login v2 flow. (What if you use multiple flows with Hosted Login v2? Then you’ll need to add those messages to each of those flows.) That might sound like a lot of work but, as it turns out, there’s an API operation that can add the 2FA messages for you. All you have to do is use the POST method call that operation. For example:

curl -L -X POST \
   'https://v1.api.us.janrain.com/config/79y4mqf2rt3bxs378kw5479xdu/flows/moreJTL/
2faMessages' \
    -H 'Authorization: Basic eTR4Zmc2ZjQ0bXNhYzN2ZXBqanZ4Z2d6dnQzZTNzazk6OTVjY3hrN2N6Y
nZ1eng2ZHB0ZTVrOXA2ZGo1Ynpla3U='

A few things to note about this API call:

In the preceding example, be sure to replace 79y4mqf2rt3bxs378kw5479xdu with your application ID, and replace moreJTL with the name of your Hosted Login v2 flow. For example, if your application ID is htb8fuhxnf8e38jrzub3c7pfrr and your flow name is standard, your API call will look like this:

curl -L -X POST \
     'https://v1.api.us.janrain.com/config/htb8fuhxnf8e38jrzub3c7pfrr/flows/standard/
  2faMessages' \
      -H 'Authorization: Basic eTR4Zmc2ZjQ0bXNhYzN2ZXBqanZ4Z2d6dnQzZTNzazk6OTVjY3hrN
  2N6YnZ1eng2ZHB0ZTVrOXA2'

Use Basic authentication when making your API call: remember, you’re using the Identity Cloud Configuration APIs here and not the Hosted Login APIs. In Postman, use the client ID of your owner client as the username and the client secret of the owner client as the password.
Don’t include any other parameters, of any kind.

Calling the /config/{appId}/flows/{flow}/2faMessages operation automatically adds a 2FAMessages section to your flow, This section includes the three allowed message types (secondFactor, resendVerification, and registrationVerification):

You might note that the /config/{appId}/flows/{flow}/2faMessages operation doesn’t let you specify a locale for your messages: the operation only adds an en-US version of each message. However, you can use other 2FA message APIs to add localized versions of these messages as needed.

Note, too that you can only call the /config/{appId}/flows/{flow}/2faMessages operation once per flow. If you run the operation against a flow and then try to run the operation a second time against that same flow, your API call fails with the following error:

And one more thing: at the moment, you can’t delete your 2FA messages. If you add the 2FA messages to a flow and then decide, for whatever reason, that you’d prefer not to have those messages in the flow, well, there’s no way to remove them. To do that, you’ll need to restore a previous version of the flow, one that doesn’t include the 2FA messages.

📘
As long as we’re on the subject, you can’t create new 2FA messages, either. However, you can modify the text of the three default messages (secondFactor, resendVerification, and registrationVerification).