/config/{app}/flows/{flow}/links/{link}

By default, an Identity Cloud flow includes a handful of links that enable users to access additional information when logging in or registering, or when modifying their user profile. For example, in Hosted Login the traditionalRegistration screen includes a pair of these links (terms of service and privacy policy) which enable users to access information without leaving the registration screen:

The  /config/{app}/flows/{flow}/links{link} endpoint and the GET method enables you to return detailed information about a specific link, and the PUT method provides a way for you to change the property values of a link (for example, if your privacy policy now has a new URL). You can also use the DELETE method to remove a link from the flow.

To return a list of all your links (or to create a new link), use the  /config/{app}/flows/{flow}/links endpoint.

The /config/{app}/flows/{flow}/links{link} endpoint supports the following methods:

• GET
• PUT
• DELETE
   

GET

Description

Returns detailed information about a link.

Base URL

The base URL for this endpoint is your Identity Cloud API URL, including the appropriate region. For example, if you are in the US region, then your base URL will look like this:

If you are in the Australian (AU) region your base URL will look like this:

URL Path Parameters

Query Parameters

The following query parameters can also be used with this endpoint:

Authentication

This endpoint requires Basic authentication.

How to Create an Authentication String

Sample Request (curl)

The following command returns information about the linkHelp link contained in a flow named testFlow:

curl -X GET \
  'https://v1.api.us.janrain.com/config/79y4mqf2rt3bxs378kw5479xdu/flows/testFlow/links/linkHelp' \
  -H 'Authorization: Basic eTR4Zmc2ZjQ0bXNhYzN2ZXBqanZ4Z2d6dnQzZTNzazk6OTVjY3hrN2N6YnZ1eng2ZHB0ZTVrOXA2ZGo1Ynpla3U='

Responses

200 OK

If your call to this endpoint succeeds you’ll get a response containing detailed information about the link:

{
    "elementHref": "#",
    "elementText": {
         "key": "12ed346de096c8dd8f5407ad1aa4aaa6",
         "path": "fields.linkHelp.elementText",
         "values": {
            "en-US": "Visit our help center.",
             "fr-CA": "Visitez notre centre d'aide.",
             "he": "",
             "it-IT": ""
        },
         "_self": "/config/79y4mqf2rt3bxs378kw5479xdu/flows/testFlow/translations/12ed346de096c8dd8f5407ad1aa4aaa6"
     },
     "name": "linkHelp",
     "_self": "/config/79y4mqf2rt3bxs378kw5479xdu/flows/testFlow/links/linkHelp"
 } 

If you included the locale parameter then the API response will look similar to this, with the returned data being limited to the specified locale:

{
    "elementHref": "https://identitydocs.akamai.com",
    "elementText": "Visitez notre centre d'aide.",
    "name": "linkHelp",
    "_self": "/config/79y4mqf2rt3bxs378kw5479xdu/flows/testFlow/links/linkHelp"
}

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

Updates a link defined within an Identity Cloud flow.

Base URL

The base URL for this endpoint is your Identity Cloud API URL, including the appropriate region. For example, if you are in the US region, then your base URL will look like this:

If you are in the Australian (AU) region your base URL will look like this:

URL Path Parameters

Body Parameters

Properties and property values for the link being updated must be defined as JSON (JavaScript Object Notation) key/value pairs within the body parameter of your API call. For example, if you are using Postman your body parameter should look similar to this:

Note that you must specify all the required properties and property values of a link 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 elementText property (a required property) your API call will fail with the following 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 target and the elementAttributes keys are optional: if these keys are not included in the body parameter your API call will not fail. However:

• The target will revert to the default value of opening in the current tab.
• The elementAttributes key (and its values) will be deleted.

The following keys are available when updating a link:

Authentication

This endpoint requires Basic authentication.

How to Create an Authentication String

Sample Request (curl)

The following command changes the value of the elementHref property for the linkHelp link. Note that even though elementHref is the only property value being changed, all the other properties of the link (and their current values) must be included in the body parameter:

curl -X PUT \
   'https://v1.api.us.janrain.com/config/79y4mqf2rt3bxs378kw5479xdu/flows/testFlow/links/linkHelp' \
   -H 'Content-Type: application/json' \
   -H 'Authorization: Basic eTR4Zmc2ZjQ0bXNhYzN2ZXBqanZ4Z2d6dnQzZTNzazk6OTVjY3hrN2N6YnZ1eng2ZHB0ZTVrOXA2ZGo1Ynpla3U=' \
   -d '{
     "elementHref": "https://identitydocs.akamai.com",
     "elementText": {
         "key": "12ed346de096c8dd8f5407ad1aa4aaa6",
         "path": "fields.linkHelp.elementText",
         "values": {
             "en-US": "Visit our help center."
         }
     },
     "name": "linkHelp",
     "target": "_blank"
 }' 

Responses

204 No Content

If your call to this endpoint succeeds you will get back the HTTP status code 204 No Content. No other data is returned.

Error Response Codes

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

DELETE

Description

Removes the specified link from the flow.

Base URL

The base URL for this endpoint is your Identity Cloud API URL, including the appropriate region. For example, if you are in the US region, then your base URL will look like this:

If you are in the Australian (AU) region your base URL will look like this:

     
URL Path Parameters

Query Parameters

The following query parameters can also be used with this endpoint:

Authentication

This endpoint requires Basic authentication.

How to Create an Authentication String

Sample Request (curl)

This command deletes a link named testLink2 from the flow testFlow:

curl -X DELETE \
  'https://v1.api.us.janrain.com/config/79y4mqf2rt3bxs378kw5479xdu/flows/testFlow/links/testLink2' \
  -H 'Authorization: Basic eTR4Zmc2ZjQ0bXNhYzN2ZXBqanZ4Z2d6dnQzZTNzazk6OTVjY3hrN2N6YnZ1eng2ZHB0ZTVrOXA2ZGo1Ynpla3U='

Responses

204 No Content

If your call to this endpoint succeeds you will get back the HTTP status code 204 No Content. No other data is returned.

Error Response Codes

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

abcdefg:hijklmnop

echo -n "abcdefg:hijklmnop" | base64

[Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes("abcdefg:hijklmn"))