/config/{appId}/flows/{flow}/upgrades /{upgradeId}

Migrates a flow to the specified version of Hosted Login. Use the GET method to return a detailed listing of the fields, translations, and screens that will be added or deleted during the migration, and use the POST method to carry out the migration.

This endpoint supports the following methods:


GET

Description

The GET method 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.


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.



POST

Back to top


Description

The POST method 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:


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.


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.