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

Last Modified on 02/25/2021 7:04 am PST

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:


Parameter

Type

Required

Description

{appId}

string


Yes

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


{flow}

string

Yes

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}

string

Yes

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


{message}

string

Yes

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


  • registrationVerification
  • resendVerification
  • secondFactor



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:

owner
access_issuer
direct_access
direct_read_access
login_client
Yes
No
Yes
No
No



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.


Response Code

Description

404

Not Found. The specified message is not in the flow. Note that you can only add messages to the flow by calling the /config/{appId}/flows/{flow}/locales/{locale}/2faMessages endpoint, an endpoint which adds all three 2FA messages to the flow. That means that if any one of those three messages is missing, the odds strongly suggest that the other two messages are missing as well.




PUT


Description


Modifies the specified 2FA message.


URI Parameters


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


Parameter

Type

Required

Description

{appId}

string


Yes

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


{flow}

string

Yes

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}

string

Yes

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


{message}

string

Yes

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

Description

sms

Text for messages sent by SMS messaging.


email

Parent property for the subject, textBody, and htmlBodyproperties.


subject

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


textBody

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


htmlBody

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:

owner
access_issuer
direct_access
direct_read_access
login_client
Yes
No
Yes
No
No



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.


Response Code

Description

400

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


404

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).



Rate this Article

How would you rate this article?
Thank you for your feedback!
Copyright © 2015 – 2016 Your Company, LLC. All rights reserved.