Modify a Hosted Login Link

Endpoint URL: {identityDomain} /config/{appId} /flows/{flow} /links/{link}



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:

https://v1.api.us.janrain.com

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

https://v1.api.au.janrain.com 


URL Path Parameters

Parameter

Type

Description

{app}

string

Unique identifier of the Identity Cloud application associated with the links.

{flow}

string

Name of the Identity Cloud flow containing the link to be modified.

{link}

string

Name of the link to be modified.


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:

Key

Type

Required

Description


name

string

Yes

Name of the link. This key must be included in your API call, but any value you assign to it will be ignored. That’s because you can’t use this endpoint to change the name of a link.

elementHref

string

Yes

URL of the page to be opened when the link is clicked. 

elementText

object

Yes

JSON-formatted key/value pair that points to a translation key containing the actual text of the link (for example, terms of service). Note that the key-value pair must be enclosed in curly braces:

{"key": "85ae9bc6-6645-4aae-bb67-3fb028bf2f7c"}

The endpoint can only be used to point the link towards a different translation key. If you simply want to change the text value assigned to the current translation key, use the /config/{app}/flows/{flow}/translations/{key} instead. 

target

string

No

HTML target value that specifies how the referenced page should be opened. It’s recommended that target be set to _blank; that causes the referenced page to open in either a new window or a new browser tab, depending on how the user’s browser has been configured. 

If this parameter is not included then the targetdefaults to opening the specified URL in the current tab.

elementAttributes

object

No

Provides a way for “extra” key/value pairs to be assigned to the link. These key/value pairs are not used by Hosted Login, but provide additional information about the link.


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.

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.

Response Code

Description

404

Link not found. You specified the name of a link that is not defined within the flow.