Endpoint URL: {identityDomain} /config/{appId} /flows/{flow} /links
Description
Creates a new link in the specified flow and the specified Identity Cloud application.
Respects the API Client Allow List: No
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
Parameter | Type | Description |
---|---|---|
{app} | string | Unique identifier of the Identity Cloud application associated with the links. |
{flow} | string | Name of the Identity Cloud flow where the new link will be created. |
Body parameters
Properties and property values for the new link 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:
The following keys are available when creating a link:
Key | Type | Required | Description | |
---|---|---|---|---|
name | string | Yes | Name of the new the link. Links names must be unique within a flow; however, Flow A and Flow B can both contain a link named myLink. | |
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"} This translation key must be created before you attempt to create a link. However, you can change the text of a link at any time either by changing the value of the translation key or by setting elementText to a different translation key. | |
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 target defaults 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)
This command creates a new link (testLink) in a flow named testFlow:
curl -X POST \
'https://v1.api.us.janrain.com/config/79y4mqf2rt3bxs378kw5479xdu/flows/testFlow/links' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic eTR4Zmc2ZjQ0bXNhYzN2ZXBqanZ4Z2d6dnQzZTNzazk6OTVjY3hrN2N6YnZ1eng2ZHB0ZTVrOXA2ZGo1Ynpla3U=' \
-d '{
"name": "testLink",
"elementHref": "https://learn.akamai.com/en-us/products/cloud_security/identity_cloud.html",
"target": "_blank",
"elementText": {
"key": "85ae9bc6-6645-4aae-bb67-3fb028bf2f7c"
}
}'
Responses
201 Created
If your call to this endpoint succeeds you’ll get back an API response containing detailed information about the link:
{
"elementText": {
"key": "85ae9bc6-6645-4aae-bb67-3fb028bf2f7c",
"path": "fields.testLink2.elementText",
"values": {
"en-US": "<h2><em>This is a test link.</em></h2>",
"fr-CA": "",
"he": "",
"it-IT": ""
},
"_self": "/config/79y4mqf2rt3bxs378kw5479xdu/flows/testFlow/translations/85ae9bc6-6645-4aae-bb67-3fb028bf2f7c"
},
"elementHref": "https://learn.akamai.com/en-us/products/cloud_security/identity_cloud.html",
"name": "testLink2",
"_self": "/config/79y4mqf2rt3bxs378kw5479xdu/flows/testFlow/links/testLink2"
}
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 | Flow not found. You referenced the name of a flow that can’t be found in the specified application. Use the /config/{app}/flows endpoint to return the names of all the flows in the application. |
409 | Link 'testLink' already exists in flow fields section! You’ve specified a link name that’s already being used. Change the name of the link and try your API call again. |