--- title: Migrating JavaScript apps to the Orchestration SDK description: PingOne Advanced Identity Cloud PingAM JavaScript component: orchsdks page_id: orchsdks:journey:migration/javascript canonical_url: https://developer.pingidentity.com/orchsdks/journey/migration/javascript.html revdate: Tue, 7 Apr 2026 14:57:06 +0100 section_ids: package_dependency_changes: Package dependency changes code_change_examples: Code change examples initialization_and_configuration: Initialization and configuration authentication_and_journeys: Authentication and Journeys token_management_and_oauth_2_0_flows: Token management and OAuth 2.0 flows migrating_using_ai_assistants: Migrating using AI assistants --- # Migrating JavaScript apps to the Orchestration SDK [icon: circle-check, set=far]PingOne Advanced Identity Cloud [icon: circle-check, set=far]PingAM [icon: js, set=fab]JavaScript The new Orchestration SDK for JavaScript aims to provide a more modern, efficient, and developer-friendly experience than the legacy ForgeRock SDK. Some of the shifts in methodology are outlined below: * **Async-first initialization** Orchestration SDK clients are initialized asynchronously with factory functions, including `journey()` and `oidc()`. * **Instance-based APIs** Methods are called on client instances, not static classes. * **Modularized packages** A significant breakdown into smaller, specialized modules, including clients for Journeys (`@forgerock/journey-client`), OIDC (`@forgerock/oidc-client`), Device management (`@forgerock/device-client`), and PingOne Protect (`@forgerock/protect`), and more. * **Explicit error handling** Response objects contain an `{ error }` property, instead of throwing exceptions. * **Well-known endpoint discovery** Only `serverConfig.wellknown` is required. All paths are derived automatically from the response. * **Removed the built-in HTTP client** Choose how your app makes protected API requests, with manual token retrieval and header management. * **Config is now fixed at creation** Per-call config overrides have been removed; you'll now create separate client instances for different environments or configurations. ## Package dependency changes The modular architecture of the Orchestration SDKs means you only have to import the functionality you require in your apps. The table below shows the packages available in the new Orchestration SDK for JavaScript: **Journey-related dependencies in the JavaScript SDK** | ForgeRock SDK | Orchestration SDK | Description | | --------------------------- | --------------------------- | ---------------------------------------------------------------------------------------- | | `@forgerock/javascript-sdk` | `@forgerock/journey-client` | Navigating authentication journeys. | | `@forgerock/javascript-sdk` | `@forgerock/oidc-client` | OAuth 2.0 and OIDC token management, user info, and logout. | | `@forgerock/javascript-sdk` | `@forgerock/sdk-types` | Shared types and enums. | | `@forgerock/javascript-sdk` | `@forgerock/device-client` | Device profiling and management, including OATH, Push, WebAuthn, Binding, and Profiling. | | `@forgerock/ping-protect` | `@forgerock/protect` | PingOne Protect (Signals) integration. | ## Code change examples ### Initialization and configuration The legacy ForgeRock SDK uses a global static `Config.set()`. The new Orchestration SDK for JavaScript uses asynchronous factory functions, each returning an independent client instance. | ForgeRock SDK | Orchestration SDK | Notes | | ----------------------------------------------------------------------------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `import { Config } from '@forgerock/javascript-sdk'` | `import { journey } from '@forgerock/journey-client'` | Journey client factory.Learn more in [Installing the Journey module in JavaScript](../usage/javascript/02-installing-the-journey-module.html). | | N/A | `import { oidc } from '@forgerock/oidc-client'` | OIDC client factory is now a separate package | | `Config.set({ clientId, redirectUri, scope, serverConfig, realmPath, tree })` | `const journeyClient = await journey({ config })` | Initialize asynchronously, with config being per-client, not global.Learn more in [Configuring the Journey module in JavaScript](../usage/javascript/03-configuring-the-journey-module.html). | ### Authentication and Journeys | ForgeRock SDK | Orchestration SDK | Notes | | -------------------------------------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `FRAuth.start({ tree: 'Login' })` | `journeyClient.start({ journey: 'Login' })` | Journey name is now passed per-call by using the `journey` parameter, not in the client config.Learn more in [Starting an authentication journey in JavaScript](../usage/javascript/04-starting-an-authentication-journey.html). | | `FRAuth.next(step, { tree: 'Login' })` | `journeyClient.next(step)` | No need to repeat the journey config inside `next()`.Learn more in [Navigating an authentication journey in JavaScript](../usage/javascript/05-navigating-an-authentication-journey.html) | | N/A | `await journeyClient.terminate()` | Ends the session by using the `/sessions` endpoint.Learn more in [Signing users out](../usage/javascript/06-handling-sessions.html#signing-users-out). | ### Token management and OAuth 2.0 flows | ForgeRock SDK | Orchestration SDK | Notes | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `TokenStorage.get()` | `const tokens = await oidcClient.token.get()` | Now part of oidcClient. Auto-retrieves from storage.Check errors with `if ('error' in tokens)`Learn more in [Managing OIDC tokens](../usage/javascript/06-handling-sessions.html#managing-oidc-tokens). | | `TokenManager.getTokens({ forceRenew: true })` | `await oidcClient.token.get({ forceRenew: true, backgroundRenew: true })` | Now a single call, with auto-renewal.Returns tokens or an error.Learn more in [Managing OIDC tokens](../usage/javascript/06-handling-sessions.html#managing-oidc-tokens). | | 1. `TokenManager.getTokens()` 2. Manual `code` and `state` | 1) `await oidcClient.authorize.background()` 2) `await oidcClient.token.exchange(code, state)` | Now uses a two-step process to authorize, when you need explicit control.Learn more in [Managing OIDC tokens](../usage/javascript/06-handling-sessions.html#managing-oidc-tokens). | | `TokenManager.deleteTokens()` | `await oidcClient.token.revoke()` | Revokes tokens remotely and deletes locally.Learn more in [Managing OIDC tokens](../usage/javascript/06-handling-sessions.html#managing-oidc-tokens). | | `TokenStorage.set(tokens)` | Handled automatically by `oidcClient.token.exchange()` | Tokens are now automatically stored after exchange. | | `TokenStorage.remove()` | `await oidcClient.token.revoke()` | Now a combined revoke and delete.Learn more in [Managing OIDC tokens](../usage/javascript/06-handling-sessions.html#managing-oidc-tokens). | ## Migrating using AI assistants To help you migrate applications from the legacy ForgeRock SDK for JavaScript to the new Orchestration SDK for JavaScript using an AI assistant, we have created a `MIGRATION.md` file, and an `interface_mapping.md` file. These file contain detailed mappings and example snippets of changes between the two SDK versions, which AI assistants can utilize to help you migrate your app. [icon: square-github, set=fab, size=3x] #### [MIGRATION.md](https://github.com/ForgeRock/ping-javascript-sdk/blob/main/MIGRATION.md) View and download the ForgeRock SDK to Orchestration SDK MIGRATION.md file for JavaScript. [icon: square-github, set=fab, size=3x] #### [interface\_mapping.md](https://github.com/ForgeRock/ping-javascript-sdk/blob/main/interface_mapping.md) View and download the ForgeRock SDK to Orchestration SDK interface\_mapping.md file for JavaScript. This approach is designed to reduce manual effort and improve consistency during the migration process.