/config/{appId}/flows/ {flow}/links | Akamai Identity Cloud Education Center

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 links (terms of service and privacy policy) that enable users to access information without leaving the registration screen:

The /config/{app}/flows/{flow}/links endpoint and the GET method enable you to return information about all the links defined within a flow. In addition, the POST method provides a way for you to create custom links of your own. Because links are a type of field, that means that you can later add these links to, say, any of your Hosted Login forms, using the same approach employed to add any field to a Hosted Login form.

And, on top of all that, you can modify the properties of an existing link (or to delete an existing link) by using the /config/{app}/flows/{flow}/links/{link} endpoint.

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

GET
POST

GET

Description

Returns a collection of all the links defined within the specified flow and the specified Identity Cloud application.

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 where the links are defined.

Authentication

This endpoint requires Basic authentication.

How to Create an Authentication String

Sample Request (curl)

This command returns all the links associated with application 79y4mqf2rt3bxs378kw5479xdu and a flow named testFlow:

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

Responses

200 OK

If your call to this endpoint succeeds you’ll get back information about all the links contained in testFlow:


[
    {
        "_self": "/config/79y4mqf2rt3bxs378kw5479xdu/flows/testFlow/links/linkHelp",
        "name": "linkHelp"
    },
    {
        "_self": "/config/79y4mqf2rt3bxs378kw5479xdu/flows/testFlow/links/linkPrivacyPolicy",
        "name": "linkPrivacyPolicy"    },
    {
        "_self": "/config/79y4mqf2rt3bxs378kw5479xdu/flows/testFlow/links/linkTermsOfService",
        "name": "linkTermsOfService"    }
]

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 which can’t be found in the specified application. Use the /config/{app}/flows endpoint to return the names of all the flows contained in the application.

POST

Description

Creates a new link in the specified flow and the specified Identity Cloud application.

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

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.

How to Create an Authentication String

To create an authentication string, combine your API client ID, a colon (:), and your client secret into a single value. For example, if your client ID is abcdefg and your client secret is hijklmnop, that value would look like this:

abcdefg:hijklmnop

Next, take the string and base64 encode it. For example, on a Mac, you can base encode the string using this command:

echo -n "abcdefg:hijklmnop" | base64

If you’re running Microsoft Windows, you can encode the string by using a Windows PowerShell command similar to this:

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

The resulting value (e.g., YWJjZGVmZzpoaWprbG1ub3A=) should be used in your authentication header.

If you are making API calls using Postman, select Basic Auth as your identification type, then use the client ID as the username and the client secret as the password.

Before you actually try your authentication string, make sure that your API client has the all the permissions (for example, the right to read user profile information) needed to complete the API call.