Endpoint URL: {identityDomain} /config/{appId} /flows/{flow} /upgrades/{upgradeId}
Description
This endpoint effectively does a “dry run” in regards to migrating a flow to a more-recent version of Hosted Login: the GET method returns information about all the fields, translations, and screens that need to be added (or, in some cases, deleted) from a flow in order to make it compatible with the specified version of Hosted Login. For example, suppose you call the GET method and get back the following response:
"itemsToAdd":[
"fields.textReturnToRp"
],
"itemsToDelete": [
"fields.traditionalRegistrationForm.nex
]
}
This response indicates that the flow is already all-but compatible with Hosted Login v2: no items need to be deleted, and only one item (the textReturnToRp field) needs to be added. If you now call the POST method, your API call will do just that: add the textReturnToRp field and then call it good.
Note. Admittedly, the GET method typically returns a much bigger to-do list than the one shown above. For a more-realistic API response (one that we didn’t show here simply because of the size of the response) see the appendix to this article.
Note that it’s possible to get back an API response that looks like this:
{ "itemsToAdd": [], "itemsToDelete": [] }
If the API response shows that there’s nothing to add or to delete, that simply means that the flow is already fully-compatible with the specified version of Hosted Login.
Respects the API Client Allow List: No
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 containing the flow to be migrated. |
{flow} | string | Yes | Name of the flow to be migrated to a more-recent version of Hosted Login. |
{upgradeId} | string | Yes | Unique identifier for the version of Hosted Login you want to migrate the flow to. Available upgrade identifiers can be returned by using the /config/{appId}/flows/{flow}/upgrades endpoint and the GET method. |
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 items that need to be added (or deleted) in order to make the flow upgradedFlow compatible with Hosted Login v2:
curl -L -X GET \
'https://v1.api.us.janrain.com/config/79y4mqf2rt3bxs378kw5479xdu/flows/upgradedFlow/upgrades/hosted_login_v2' \
-H 'Authorization: Basic eTR4Zmc2ZjQ0bXNhYzN2ZXBqanZ4Z2d6dnQzZTNzazk6OTVjY3hrN2N6YnZ1eng2ZHB0ZTVrOXA2ZGo1Ynpla3U='
Responses
200 OK
If your call to this endpoint succeeds, you’ll get information about everything that needs to be done to upgrade the flow to the specified version of Hosted Login. For example:
{
"itemsToAdd": [
"2faMessages",
"fields.textReturnToRp",
"fields.textPasswordTitle",
"fields.textEmailTitle",
"fields.textAddEmailTitle",
"fields.textChangeEmailTitle",
"fields.textChangeEmailValue",
"fields.textEmailVerified", ],
"itemsToDelete": []
}
Note. As mentioned previously, the preceding API response is much shorter than the typical response (i.e., it has far fewer items to add or delete). See the appendix for examples of API responses you’re more likely to see.
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. Typically occurs when you request an invalid version of Hosted Login. For example, if your API call tries to upgrade to Hosted Login v5 (hosted_login_v5), that call fails with the following error. { "errors": "Upgrade hosted_login_v5 not found." }That's because there isn't a v5 upgrade for Hosted Login. You’ll get this same error if your call references and invalid application ID or flow name. |