Add 2FA messages

Hosted Login v2 includes three new messages that can be sent to the end user via email or SMS for verification purposes. They are:

  • registrationVerification - Sends a code to the end user’s email address for verification during account creation.
  • resendVerification - Sends a code to the end user if they request a new verification.
  • secondFactor - Sends a code to the end user during the 2FA process to complete a login.

Examples of the secondFactor message: 2FA SMS message

If you completed the previous step, Add new strings, then you’ve already added the new email and SMS messages to the flow.

Below, we cover an alternate method for adding the new email and SMS messages, as well as how to customize them. You can do this using the Identity Cloud Flow Configuration API, which we’ll step through next.

In this section, you’ll make RESTful API calls to the Identity Cloud using your platform or language of choice. We provide complete sample calls in cURL format.

NOTE: If your region and application ID are not populated in the API examples below, go back and complete the Gather Your Details section, then return to this page.

New to making API calls?

These calls require Basic Authorization. To create the authorization code for these calls, your application owner Client Id and Secret must be combined with a colon in between (id:secret) and then base64 encoded.

Find my application owner Client Id and Secret
How to create the authorization code in Postman

Add 2FA messages to your flow

The 2FA messages are customized via your flow configuration. Depending on when your flow was originally provisioned, it may not contain the 2FA messages yet.

If the 2FA messages haven’t been added to your flow, Hosted Login will send the default messages.

To add the 2FA messages to your flow, make an API call to the /2faMessages endpoint using the POST method.

EXAMPLE:

curl -X POST \
https://v1.api.us.janrain.com/config/a1bcde2fg3h456ijk7l8mnop9q/flows/standard/2faMessages \
	-H 'Authorization: Basic AUTHORIZATION CODE'
Response Status Response Body Outcome
204 No Content Empty The call was successful and the 2FA messages have been added to your flow.
409 Conflict {"errors": "This flow already has 2faMessages."} Your flow already contains the 2FA messages.

View 2FA messages

To view the current 2FA message you want to customize, first make an API call to the /locales/en-US/2faMessagesendpoint using the GET method.

The default 2FA messages are in US English. You can add translations for other languages later.

EXAMPLE:

curl -X GET \
https://v1.api.us.janrain.com/config/a1bcde2fg3h456ijk7l8mnop9q/flows/standard/locales/en-US/2faMessages \
	-H 'Authorization: Basic AUTHORIZATION CODE'

A successful response will list the names of the three 2FA messages available:

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

To view the specific 2FA message you want to customize, make an API call to the /locales/en-US/2faMessages/<messageName> endpoint using the GET method.

The following example targets the secondFactor message, which is sent during the 2FA login process:

curl -X GET \
https://v1.api.us.janrain.com/config/a1bcde2fg3h456ijk7l8mnop9q/flows/standard/locales/en-US/2faMessages/secondFactor \
	-H 'Authorization: Basic AUTHORIZATION CODE'

A successful response looks something like 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/a1bcde2fg3h456ijk7l8mnop9q/flows/standard/locales/en-US/2faMessages/secondFactor"
}

Note that the SMS message, email message and email subject line are all configured separately. There’s also separate HTML and text-only versions of the email message, which allows the message to render even for email platforms that do not handle HTML.

Update 2FA messages

To update the specific 2FA message you want to customize, copy the full JSON object from the response and paste it into a text editor, where you can revise the message values as desired.

Then make an API call to the /locales/en-US/2faMessages/<messageName> endpoint using the PUT method, passing the full, updated JSON into the body of the call.

The following example updates the secondFactor message:

curl -X PUT \
https://v1.api.us.janrain.com/config/a1bcde2fg3h456ijk7l8mnop9q/flows/standard/locales/en-US/2faMessages/secondFactor \
	-H 'Authorization: Basic AUTHORIZATION CODE' \
	-H 'Content-Type: application/json' \
	-d '{
		"sms": "Your secure access code from {{site_name}} is: {{code}}",
		"email": {
			"subject": "{{site_name}} Access Code",
			"textBody": "Your secure access code from {{site_name}} is: {{code}}",
			"htmlBody": "<p>Your secure access code from {{site_name}} is: {{code}}<∕p>"
		}
	}'

Tip! The _self property is not configurable and can be safely removed from the JSON for simplicity, as in the example above.

Response Status Response Body Outcome
204 No Content Empty The call was successful and the 2FA message has been updated.

Learn More

For more details on 2FA messages, including how to translate them into additional languages, see Manage two-factor authentication (2FA).