> For the complete documentation index, see [llms.txt](https://docs.parallels.com/landing/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.parallels.com/landing/ras-client-integration-guide/ras-web-client-api/migrating-from-the-legacy-web-client-api.md).

# Migrating from the Legacy Web Client API

The legacy Web Client API — passing launch data and credentials through a JavaScript payload URL (`?appinfo=https://.../appinfo.js`) consumed by `_RASWebClientLoadApp` / `_RASHTML5LoadApp` is **deprecated**. It has been replaced by the [**Authentication Handoff API**](/landing/ras-client-integration-guide/ras-web-client-api/authentication-handoff-api.md), which is more secure: credentials and launch data are submitted in a POST body directly to the RAS Secure Gateway instead of being exposed through a URL and a publicly fetchable JavaScript payload.

{% hint style="warning" %}
**Attention**: The legacy API is disabled by default starting with Parallels RAS 21.2. When you upgrade to 21.2 or later, integrations that still use the **appinfo** mechanism will stop working until they are migrated.

Re-enabling the legacy API is possible but strongly discouraged and should only ever be used as a temporary measure while you complete the migration. For instructions on re-enabling the deprecated API and updating your code, see [this KB article](https://kb.parallels.com/en/131148).
{% endhint %}

### What changes for your integration

* **GET becomes POST.** Stop passing launch data through a JS payload URL. Submit the payload to POST `https://<user-portal-domain>/userportal/auth-handoff` instead.
* **No hosted payload file.** You no longer host or dynamically generate an **appinfo.js** file. The payload is the POST body.
* **No JavaScript function call.** `_RASWebClientLoadApp` and `_RASHTML5LoadApp` are not used.
* **Redirect-based result.** The Gateway responds with a `3xx` redirect (typically `302`) which the browser follows to the User Portal.
* **No token handling.** Token creation, validation, and session handling are managed by the User Portal Gateway. Your integration never inspects JWT contents.

### Parameter mapping

<table data-header-hidden="false" data-header-sticky><thead><tr><th width="266.75390625">Legacy</th><th>New</th><th>Notes</th></tr></thead><tbody><tr><td><strong>?appinfo=https://.../appinfo.js</strong></td><td><strong>POST /auth-handoff</strong></td><td>Stop passing launch data through a JS URL.</td></tr><tr><td><strong>u</strong></td><td><strong>username</strong></td><td>Username field renamed for clarity.</td></tr><tr><td><strong>q</strong></td><td><strong>password</strong></td><td>Password.</td></tr><tr><td><strong>a</strong></td><td><strong>appid</strong></td><td>Published resource ID. Optional.</td></tr><tr><td><strong>logonURL</strong></td><td><strong>login</strong></td><td>URL to redirect to the IDP login page on User Portal refresh. Optional.</td></tr><tr><td><strong>logoutURL</strong></td><td><strong>logout</strong></td><td>URL to redirect to the IDP logout page upon User Portal logout. Optional.</td></tr><tr><td><strong>theme</strong> (URL parameter)</td><td><strong>theme</strong></td><td>Now part of the POST payload.</td></tr><tr><td><strong>p</strong></td><td><strong>p</strong></td><td>Additional launch parameters string. Unchanged.</td></tr><tr><td><strong>extra</strong></td><td><strong>extra</strong></td><td>Per-session redirection settings. Unchanged.</td></tr></tbody></table>

### Migration steps

1. Replace the code that generates the appinfo.js payload and opens the Web Client URL with a single POST of the JSON payload to /auth-handoff (see [**Authentication Handoff API**](/landing/ras-client-integration-guide/ras-web-client-api/authentication-handoff-api.md) and [**Example**](/landing/ras-client-integration-guide/ras-web-client-api/authentication-handoff-api/example.md)).
2. Rename the payload fields according to the mapping table above.
3. If your frontend does not hold the user's credentials, initiate the POST from your backend and relay the redirect to the browser (see [**Backend-Initiated Handoff**](/landing/ras-client-integration-guide/ras-web-client-api/authentication-handoff-api/backend-initiated-handoff.md)).
4. Remove the hosted payload endpoint from your web server once the migration is verified.
5. Test against a Parallels RAS environment running 21.2 or later with the legacy API in its default (disabled) state.

### Timeline

<table data-header-hidden="false" data-header-sticky><thead><tr><th width="345.66796875">Parallels RAS version</th><th>Legacy Web Client API status</th></tr></thead><tbody><tr><td>Up to 21.1</td><td>Available (deprecated). Migrate now.</td></tr><tr><td>21.2 or later</td><td><strong>Disabled by default.</strong> Can be temporarily re-enabled (not recommended). See <a href="https://kb.parallels.com/en/131148">this KB article</a>.</td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.parallels.com/landing/ras-client-integration-guide/ras-web-client-api/migrating-from-the-legacy-web-client-api.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.