View Hosted Login Upgrade Requirements

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:

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:

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.

{
    "errors": "Upgrade hosted_login_v5 not found."
}