/config/{appId}/flows/{flow}/locales/{locale}/ 2faMessages/{message}

This endpoint manages the individual two-factor authentication (2FA) messages found in the specified flow. The GET method is used to return information about a 2FA message, while the PUT method is used to modify the text used in that message. Note that each 2FA message actually consists of three messages: an SMS message (used when 2FA access codes are sent via text messaging); a plain-text email message; and an HTML-formatted email message. All three messages types can be changed by calling this endpoint.

Although you can view and modify messages using the /config/{appId}/flows/{flow}/locales/{locale}/2faMessages/{message} endpoint, there is currently no way to delete 2FA messages or to create new 2FA messages.

This endpoint supports the following methods:

• GET
• PUT
  
  

GET

Description

Returns the specified 2FA message.

URI Parameters

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

Authentication

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 returns information about the secondFactor 2FA message.

curl -L -X GET \
    'https://v1.api.us.janrain.com/config/79y4mqf2rt3bxs378kw5479xdu/flows/
standard/locales/en-US/2faMessages/secondFactor' \
    -H 'Authorization: Basic eTR4Zmc2ZjQ0bXNhYzN2ZXBqanZ4Z2d6dnQzZTNzazk6OT
VjY3hrN2N6YnZ1eng2ZHB0ZTVrOXA2ZGo1Ynpla3U='

Responses

200 OK

If your API call succeeds you’ll get back detailed information about the message:

{
    "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": "{{site_name}}: Your secure access code is {{code}}. Do not 
share this code with anyone. {{site_name}} will never ask you for it."
    },
    "_self": "/config/79y4mqf2rt3bxs378kw5479xdu/flows/standard/locales/
en-US/2faMessages/secondFactor"
}

Error Response Codes

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

PUT

Description

Modifies the specified 2FA message.

URI Parameters

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

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:

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.

Authentication

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 \
  'https://v1.api.us.janrain.com/config/79y4mqf2rt3bxs378kw5479xdu/flows/
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>"
    }
}'

Responses

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.