Adding the 2FA Messages to Your 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 2FA screen:

The text displayed on this screen (e.g., Access Code Required) is maintained in a flow; in this case, 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 fit that tag. And that’s fine: if an element (such as a JTL tag) doesn’t exist, Hosted Login will (under the right circumstances, of course) 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 running Hosted Login v2.) 

Instead, if you want to modify (or if you to 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 endpoint (/config/{appId}/flows/{flow}/2faMessages) that can add the 2FA messages for you. All you have to do is use the POST method call this endpoint; for example:

curl -L -X POST \
2faMessages' \
    -H 'Authorization: Basic eTR4Zmc2ZjQ0bXNhYzN2ZXBqanZ4Z2d6dnQzZTNzazk6OTVjY3hrN2N6Y

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 \
    2faMessages' \
        -H 'Authorization: Basic eTR4Zmc2ZjQ0bXNhYzN2ZXBqanZ4Z2d6dnQzZTNzazk6OTVjY3hrN
  • 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 endpoint automatically adds a 2FAMessages section to your flow, This section includes the three allowed message types (sendFactor, resendVertification, and registrationVerification):

You might have noticed  that the /config/{appId}/flows/{flow}/2faMessages endpoint doesn’t let you specify a locale for your messages:the endpoint only adds an en-US version of each message. (You can find the default message text in Appendix A.) 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 endpoint once per flow. If you run the endpoint against a flow and then try to run the endpoint a second time against that same flow, your API call will fail 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.

Note. 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 (sendFactor, resendVerification, and registrationVerification).