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.


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 CodeDescription

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.