Upgrade Hosted Login

Endpoint URL: {identityDomain} /config/{appId} /flows/{flow} /upgrades/{upgradeId}



Description

This endpoint adds the fields, translations, and screens required to ensure that a flow is compatible with the specified version of Hosted Login. Keep in mind that having a compatible flow doesn’t necessareily, mean you’re ready to start using that version of Hosted Login. For examples of other tasks  that you might need to carry out when upgrading to a new version of Hosted Login, see this article for more information about migrating from Hosted Login v1 to Hosted Login v2.

Note that this endpoint can be run against the same flow as many times as you want: you could even run the endpoint and upgrade a flow and then, as soon as the API call completes, immediately run the endpoint a second time against the very same flow. On the second try, the endpoint will examine the flow, verify that the flow already is compatible with Hosted Login, and then simply terminate. If your flow is missing, say, a single field, the endpoint adds that one field to the flow and then quits. The /{upgradeId} endpoint only does as much work as needed in order to migrate the flow.

It’s also useful to keep in mind that this is a “one-way only” endpoint: although you can use it to upgrade a flow from, say, Hosted Login v1 to Hosted Login v2, you can’t use the endpoint to “downgrade” a flow from v2 to v1. Admittedly, that’s probably something you’ll never need to do. Should such an occasion arise, however, you can, instead, revert  to the version of the flow in use before you did the upgrade. If you aren’t sure which version that was, use the Console’s Registration Builder to check your flow versions; Registration Builder tells you exactly when a flow was upgraded from one version to another:


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 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 upgrades a flow named upgradedFlow to make it compatible with Hosted Login v2:

curl -L -X POST \
  'https://v1.api.us.janrain.com/config/79y4mqf2rt3bxs378kw5479xdu/flows/upgradedFlow/upgrades/hosted_login_v2' \
  -H 'Authorization: Basic eTR4Zmc2ZjQ0bXNhYzN2ZXBqanZ4Z2d6dnQzZTNzazk6OTVjY3hrN2N6YnZ1eng2ZHB0ZTVrOXA2ZGo1Ynpla3U='


Responses

204 No Content

If your API call succeeds, you won’t get back any information about the upgraded flow. Instead, you’ll simply get back the HTTP status code 204 No Content.


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."
}
You’ll get this same error if your call references and invalid application ID or flow name.