Modify a 2FA Message

Endpoint URL: {identityDomain} /config/i/flows/{flow} /locales/{locale} /2faMessages/{2faMessage}


Modifies the specified 2FA message.

Respects the API Client Allow List:  No

URI Parameters

URI parameters that must be included in the request are listed in the following table:








Unique identifier of the Identity Cloud application associated with the 2FA messages.




Name of the flow containing the 2FA messages. Note that flow names are case-sensitive: if your flow is named standard then an error occurs if you list the flow as, say,  Standard.




Locale of the flow (e.g., en-US) containing the 2FA messages. Similar to flow names, locales are also case-sensitive.




Name of the message to be updated. Allowed values are:

  • registrationVerification
  • resendVerification
  • secondFactor

Request Parameters

Properties and property values for the message being updated must be defined as JSON (JavaScript Object Notation) key/value pairs within the body parameter of your API call. For example:

  "sms": "Here's your access code for the {{site_name}} site: {code}.",
  "email": {
    "subject": "{{site_name}} Access Code",
    "textBody": "Here's your access code for the {{site_name}} site: {{code}}.",
    "htmlBody": "<p>Here's your access code for the {{site_name}} site: {{code}}.</p>"

Note that you must specify all the required properties and property values of a message when making a PUT call; this includes the values that aren’t being changed. For example, if you try to update a link without including the sms property (a required property) your API call fails with a Missing data for required field error.

A good way to work around this issue is to first use the GET method to return the current properties and property values of the link. Copy these values, paste them into the body parameter of your PUT call, and then make the needed changes.

The primary properties and property values defined in the body parameter include the following. Note that all of these property values are required; if you leave out, say, the sms property then your API call fails:

Key value



Text for messages sent by SMS messaging.


Parent property for the subject, textBody, and htmlBodyproperties.


Subject line for messages sent by email. Note that the same subject line is used for plain-text and HTML messages.


Text for plain-text messages sent by email. You can’t include any kind of formatting in your plain-text messages. 


Text sent for HTML messages sent by email. You can include HTML tags and inline CSS formatting in HTML messages.

Note that you can include the following JTL (Janrain Templating Language) tags when defining the sms, textBody, or htmlBody properties:

  • {{site_name}}. The name of your website. The value for this tag is taken from the site_name setting in your application client. If you don’t like this, that’s fine: {site_name} can safely be removed from your 2FA messages.

  • {{code}}. The access code generated by Hosted Login and sent to the user. Whatever else you do, don’t remove {{code}} from your messages. If you do, the user won’t know the access code that he or she is expected to supply in order to log in.

For example, suppose your message text includes the following:

This code was sent from the {{site_name}} site. 

If your site is named Akami Documentation, the preceding syntax renders like this:

This code was sent from the Akamai Documentation site.

API Client Permissions

The following table indicates the API clients that can (and the API clients that can't) be used to call this endpoint:



This endpoint requires Basic authentication. When configuring authentication, use your client ID as the username and your client secret as the password.

Sample Request (curl)

The following command updates the secondFactor message found in the standard flow:

curl -L -X PUT \
standard/locales/en-US/2faMessages/secondFactor' \
  -H 'Authorization: Basic eTR4Zmc2ZjQ0bXNhYzN2ZXBqanZ4Z2d6dnQzZTNzazk6OTV
jY3hrN2N6YnZ1eng2ZHB0ZTVrOXA2ZGo1Ynpla3U=' \
  -H 'Content-Type: application/json' \
  -d '{
    "sms": "Here's your access code for the {{site_name}} site: {{code}}.",
    "email": {
        "subject": "{{site_name}} Access Code",
        "textBody": "Here's your access code for the {{site_name}} site: {{code}.",
        "htmlBody": "<p>Here's your access code for the {{site_name}} site: {{code}}.</p>"


204 No Content

No API response is returned if your call succeeds. However, you will get back the HTTP status code 204 No Content.

Error Response Codes

The following table includes information about some of the other response codes that you might encounter when calling this endpoint.

Response Code



Bad request. Typically occurs if you leave out one or more properties when making your API call.


Not Found. Occurs if you specify an incorrect path to a message. This is typically due to a misspelling (e.g., secondFactr) or to incorrect letter casing (for example, secondfactor).