okta · brentschaus-okta · Jun 5, 2026 · Jun 5, 2026 · Jun 5, 2026 · Jun 5, 2026
@@ -7,6 +7,8 @@ excerpt: Okta Identity Engine introduces a lot of changes to the Okta platform.
 
 Okta Identity Engine introduces many changes to the Okta platform. Some of these changes result in a lack of support for previously available features. Also, some of these changes result in Identity Engine features not supported for use with Classic Engine APIs.
 
+> **Note:** To update your integrations for these changes, see [API changes after the upgrade](/docs/guides/oie-upgrade-api-changes/main/).
+
 To find which of these features and integrations your org actually uses, see [Identify your Okta authentication integrations and customizations](/docs/guides/oie-upgrade-identify-integrations/).
 
 Are you an admin? See the Identity Engine [limitations](https://help.okta.com/okta_help.htm?type=oie&id=ext-oie-limitations) doc for admins.
@@ -17,7 +19,7 @@ Are you an admin? See the Identity Engine [limitations](https://help.okta.com/ok
 
 ### Custom sign-in page for embedded app links
 
-**What Changed:** Using a custom sign-in page for embedded app links isn't supported. Users who click an app embed link are now evaluated by their org's Okta sign-on policy. Admins can customize an Okta-hosted sign-in page or configure an IdP routing rule for the app.
+**What Changed:** Using a custom sign-in page for embedded app links isn't supported. Users who click an app embed link are now evaluated by their org's global session policy (called the **Okta sign-on policy** in Classic Engine). Admins can customize an Okta-hosted sign-in page or configure an IdP routing rule for the app.
 
 **Further information:** [Configure a custom Okta-hosted sign-in page](/docs/guides/custom-widget/) and [Configure routing rules](https://help.okta.com/okta_help.htm?type=oie&id=ext_Identity_Provider_Discovery).
 
@@ -58,6 +60,8 @@ The following event types are available only in Identity Engine:
 
 Okta discourages the use of the Classic Engine Reset Factor operation for resetting a user's email enrollment. This is because email is an auto-enrolling authenticator in Identity Engine. A user's verified `primaryEmail` is always usable as long as the Email authenticator is set to `ACTIVE`. The user can use it for **recovery only** or for both **authentication and recovery**, depending on the Email authenticator settings.
 
+**Further information:** [Factors API changes after the upgrade](/docs/guides/oie-upgrade-api-changes/main/#factors-api-changes)
+
 ***
 
 ### Reset Factor API - question enrollment
@@ -70,6 +74,8 @@ In Identity Engine, after you reset all the factors, calling the GET `/factors`
 
 > **Note:** With Identity Engine, if a user is using both the forgot password question and a Security Question for MFA, and an API call is made to `v1/lifecycle/reset_factors` to reset all the factors for the user, just the Security Question is reset with that call. To reset the forgot password question after that first call, make a second call to `/v1/lifecycle/reset_factors`.
 
+**Further information:** [Factors API changes after the upgrade](/docs/guides/oie-upgrade-api-changes/main/#factors-api-changes)
+
 ***
 
 ### Self-Service Registration
@@ -88,7 +94,7 @@ See [Configure user profile policies](https://help.okta.com/okta_help.htm?type=o
 
 **What changed:** This POST `/api/v1/sessions?additionalFields=cookieToken` request using the Sessions API isn't supported in Identity Engine. However, your existing app could continue to work as long as session management and app interactions are fully contained within the `v1/sessions` APIs.
 
-> **Note:** See [Understand how sessions work after the upgrade](/docs/guides/oie-upgrade-sessions-api/main/).
+> **Note:** See [Understand how sessions work after the upgrade](/docs/guides/oie-upgrade-sessions-api/main/) and [Sessions API changes after the upgrade](/docs/guides/oie-upgrade-api-changes/main/#sessions-api-changes).
 
 ***
 
@@ -102,17 +108,17 @@ See [Configure user profile policies](https://help.okta.com/okta_help.htm?type=o
 
 ### SMS Factors Administration lifecycle operations
 
-**What Changed:** The SMS Factor can no longer be activated or deactivated using the Factors API (`/api/v1/org/factors`).
+**What changed:** The SMS Factor can no longer be activated or deactivated using the Factors API (`/api/v1/org/factors`).
 
-**Further information:** [Factors Administration API](/docs/reference/api/factor-admin)
+**Further information:** [Factors Administration API](/docs/reference/api/factor-admin) and [Factors API changes after the upgrade](/docs/guides/oie-upgrade-api-changes/main/#factors-api-changes)
 
 ***
 
 ### The `audience` parameter in the Authentication API
 
 **What changed:** Passing the `audience` parameter to the `/api/v1/authn` API isn't supported in Identity Engine because of the new flexible app sign-in policy that comes with Identity Engine. The Classic Engine pipeline doesn't support the flexible app sign-in policy.
 
-**Further information:** [IdP-initiated step-up authentication](/docs/reference/api/authn/#idp-initiated-step-up-authentication)
+**Further information:** [IdP-initiated step-up authentication](/docs/reference/api/authn/#idp-initiated-step-up-authentication) and [Authentication API changes after the upgrade](/docs/guides/oie-upgrade-api-changes/main/#authentication-api-changes)
 
 ***
 
@@ -138,7 +144,7 @@ See the [SDK use cases](/docs/guides/oie-embedded-common-org-setup/main/) in our
 
 If you use the `/api/v1/authn` APIs to build custom password reset and account unlock experiences, you can't use the new recovery options in Identity Engine. Specifically, if you set a password policy rule to require Okta Verify Push for recovery or configure **Any enrolled authenticator used for MFA/SSO** for additional verification, end users who use the Classic Engine authentication APIs are denied recovery.
 
-**Further information:** [Recovery operations](/docs/reference/api/authn/#recovery-operations) section of the Authentication API.
+**Further information:** [Recovery operations](/docs/reference/api/authn/#recovery-operations) section of the Authentication API, and [Factors API changes after the upgrade](/docs/guides/oie-upgrade-api-changes/main/#factors-api-changes).
 
 ***
 

@@ -167,6 +167,7 @@ guides:
  - oie-embedded-widget-use-case-basic-sign-in
  - oie-embedded-widget-use-case-sign-in-soc-idp
  - oie-upgrade-overview
+ - oie-upgrade-api-changes
  - oie-upgrade-identify-integrations
  - oie-upgrade-plan-embedded-upgrades
  - oie-upgrade-add-sdk-to-your-app

@@ -6,7 +6,7 @@ meta:
 layout: Guides
 ---
 
-> **Note**: This document is written for Classic Engine. If you’re using Identity Engine, you can find multiple guides and use cases to help you add MFA to your apps: for example, explore our [Embedded SDK use cases](/docs/guides/oie-embedded-sdk-use-case-basic-sign-in/android/main/) documentation. See [Identify your Okta solution](https://help.okta.com/okta_help.htm?type=oie&id=ext-oie-version) to determine your Okta version.
+> **Note**: This document is written for Classic Engine. If you’re using Identity Engine, you can find multiple guides and use cases to help you add MFA to your apps: for example, explore our [Embedded SDK use cases](/docs/guides/oie-embedded-sdk-use-case-basic-sign-in/android/main/) documentation. For how the Factors API behaves differently after an upgrade, see [Factors API changes after the upgrade](/docs/guides/oie-upgrade-api-changes/main/#factors-api-changes). See [Identify your Okta solution](https://help.okta.com/okta_help.htm?type=oie&id=ext-oie-version) to determine your Okta version.
 
 This guide explains how to implement multifactor authentication (MFA) and provides an example of how to use the Okta Factors API to add an additional factor for a user.
 

@@ -0,0 +1,9 @@
+---
+title: API changes after the upgrade
+meta:
+  - name: description
+    content: Understand which Okta APIs behave differently or are unsupported after upgrading to Identity Engine.
+layout: Guides
+sections:
+  - main
+---
@@ -0,0 +1,141 @@
+---
+title: API changes after the upgrade
+meta:
+  - name: description
+    content: Understand which Okta APIs behave differently or are unsupported after upgrading to Identity Engine.
+---
+
+<ApiLifecycle access="ie" />
+
+Upgrading from Classic Engine to Identity Engine changes how some Okta APIs work. A few behave differently, and others have new limitations. If your apps call the [Authentication API](#authentication-api-changes), [Factors API](#factors-api-changes), or [Sessions API](#sessions-api-changes), take a look at what's changed before you upgrade.
+
+---
+
+**Learning outcome**
+
+Understand which Okta APIs behave differently or are unsupported in Identity Engine, and update your integrations before you upgrade.
+
+**What you need**
+
+* Knowledge of which Okta APIs your apps call
+* Access to the app code that integrates with Okta APIs
+* An understanding of whether your apps use Classic Engine Authentication API flows or OAuth 2.0/OIDC flows
+
+---
+
+## Summary of API changes
+
+The following table summarizes the API changes in Identity Engine.
+
+| API area | Change type | Impact |
+| --- | --- | --- |
+| `audience` parameter in the Authentication API (`/api/v1/authn`) | Not supported | Apps that pass `audience` fail. |
+| Authentication API device token | Behavior changed | Adopt a new SDK or the redirect model. |
+| `cookieToken` in the Sessions API (`POST /api/v1/sessions`) | Not supported | You can't request `cookieToken` as an additional field. |
+| Sessions API (`/api/v1/sessions/me`) | Response changed | The response no longer returns Identity Provider information. |
+| Factors API: reset email factor | Behavior changed | Email auto-enrolls, so the reset behavior differs. |
+| Factors API: reset question factor | Behavior changed | Recovery questions appear in factor responses. |
+| Factors API: SMS lifecycle operations | Not supported | You can't activate or deactivate SMS through the Factors API. |
+| Classic Authentication API: password recovery | Limited | New Identity Engine recovery options aren't accessible through the classic API. |
+| Classic Engine APIs: Identity Engine features | Not supported | Identity Engine-only features require updated SDKs. |
+
+## Authentication API changes
+
+### The `audience` parameter isn't supported
+
+Passing the `audience` parameter to `/api/v1/authn` isn't supported in Identity Engine.
+
+**Why:** Identity Engine uses a flexible app sign-in policy model that Classic Engine authentication pipelines can't accommodate.
+
+**Action:** Remove the `audience` parameter from authentication requests. Instead, use app-specific sign-on policies that you configure in the Admin Console.
+
+### Device token behavior changed
+
+Direct device token passing is no longer the primary method for device context in Identity Engine. Identity Engine uses authentication policies to evaluate device context instead.
+
+| Migration path | Description | Trade-off |
+| --- | --- | --- |
+| Temporary backward compatibility | Keep the Okta sign-on policy active (called the **global session policy** in Identity Engine). | New Identity Engine device features remain unavailable. |
+| Redirect-based authentication | Migrate to Okta-hosted sign-in pages. | Device context policies are handled automatically. |
+| Updated SDKs | Adopt Identity Engine SDKs for embedded apps. | Full access to Identity Engine Device Trust capabilities. |
+
+See [Device Token in Auth API](https://support.okta.com/help/s/article/Device-Token-in-Auth-API?language=en_US) for details.
+
+## Sessions API changes
+
+### `POST /api/v1/sessions` with `cookieToken`
+
+The request `POST /api/v1/sessions?additionalFields=cookieToken` isn't supported in Identity Engine. Apps that manage sessions entirely within the `/api/v1/sessions` APIs can continue to work. However, you can't request the `cookieToken` extra field.
+
+### `/api/v1/sessions/me` response changes
+
+After the upgrade, the `/api/v1/sessions/me` response no longer returns Identity Provider (IdP) information.
+
+**Backward compatibility:** Existing apps continue to work without immediate changes. Embedded Sign-In Widgets and apps that use older SDKs or direct APIs still operate after the upgrade.
+
+**Limitation:** Some new Identity Engine capabilities require updated SDKs. To use passwordless authentication and app-specific sign-on policies, upgrade to SDKs that support the [Interaction Code flow](/docs/concepts/interaction-code/).
+
+See [v1/sessions/me APIs](https://support.okta.com/help/s/article/v1sessionsme-APIs?language=en_US) for details.
+
+## Factors API changes
+
+### Reset Factor API: email enrollment
+
+In Identity Engine, a verified primary email automatically functions as an email authenticator enrollment. This changes the reset factor behavior:
+
+* The `GET /api/v1/users/{userId}/factors` endpoint returns the verified primary email as an active email factor.
+* Don't use the Classic Engine reset factor operation for email enrollment, because email auto-enrolls in Identity Engine.
+* Users can use their verified primary email for recovery only, or for both authentication and recovery. This depends on the Email authenticator configuration.
+
+### Reset Factor API: question enrollment
+
+Identity Engine consolidates recovery and MFA questions into a single concept:
+
+* The `GET /api/v1/users/{userId}/factors` endpoint now returns recovery questions even when no MFA Security Question enrollment exists.
+* After you reset all factors, the forgotten-password question still appears in API responses. This differs from Classic Engine behavior.
+* Resetting both question types requires two separate `POST /api/v1/users/{userId}/lifecycle/reset_factors` calls.
+
+### SMS Factor lifecycle operations aren't supported
+
+You can't activate or deactivate the SMS factor through the Factors API (`/api/v1/org/factors`) in Identity Engine.
+
+### Password recovery limitations with the Classic Authentication API
+
+If you use the `/api/v1/authn` API for custom password reset experiences, be aware of these limitations in Identity Engine:
+
+* New Identity Engine recovery options, such as Okta Verify Push and "any enrolled authenticator" verification, aren't available through the Classic Authentication API.
+* End users are denied recovery if these modern options are the only ones configured.
+
+**Action:** If you rely on classic API password recovery flows, keep at least one Classic-compatible recovery option configured. Alternatively, migrate to the Identity Engine SDK-based recovery flow.
+
+### Identity Engine features not accessible from Classic Engine APIs
+
+Identity Engine introduces features that are only available through updated SDKs and the Interaction Code flow. Classic Engine APIs can't access these features:
+
+* Passwordless authentication
+* App-specific sign-on policies
+* Modern Device Trust evaluation
+* Advanced authenticator enrollment options
+
+**Action:** To access Identity Engine features, migrate from Classic Engine APIs to the Identity Engine SDKs that support the Interaction Code flow.
+
+## Update checklist
+
+Before you upgrade, audit your integrations against the following checklist:
+
+* Audit your code for the `audience` parameter in `/api/v1/authn` calls.
+* Audit for device token passing to the Authentication API.
+* Check whether you request `cookieToken` from the Sessions API.
+* Check whether you parse IdP information from `/api/v1/sessions/me` responses.
+* Review your Factors API usage for email reset, question reset, and SMS lifecycle operations.
+* Review custom password recovery flows that are built on `/api/v1/authn`.
+* Plan an SDK migration for any features that require Identity Engine capabilities.
+* Test your API integrations in a preview org after the upgrade.
+
+## See also
+
+* [Identity Engine limitations](/docs/guides/ie-limitations/main/): Full reference for current Identity Engine limitations and behavioral differences
+* [Session changes after the upgrade](/docs/guides/oie-upgrade-sessions-api/main/): How sessions work in Identity Engine
+* [Upgrade your app SDK](/docs/guides/oie-upgrade-api-sdk-to-oie-sdk/main/): Migrate to the Identity Engine SDKs
+* [Device Token in Auth API](https://support.okta.com/help/s/article/Device-Token-in-Auth-API?language=en_US): Device token changes and migration paths
+* [v1/sessions/me APIs](https://support.okta.com/help/s/article/v1sessionsme-APIs?language=en_US): Session API response changes
@@ -2,7 +2,7 @@
 title: Work with Okta session cookies
 ---
 
-> **Note:** This page provides information on Okta Classic Engine. If you're using Okta Identity Engine, see [Understand how sessions work after the upgrade](/docs/guides/oie-upgrade-sessions-api/) and this [Sessions APIs](/docs/guides/ie-limitations/main/#sessions-apis) section. See [Identify your Okta solution](https://help.okta.com/okta_help.htm?type=oie&id=ext-oie-version) to determine your Okta version.
+> **Note:** This page provides information on Okta Classic Engine. If you're using Okta Identity Engine, see [Understand how sessions work after the upgrade](/docs/guides/oie-upgrade-sessions-api/), [Sessions API changes after the upgrade](/docs/guides/oie-upgrade-api-changes/main/#sessions-api-changes), and this [Sessions APIs](/docs/guides/ie-limitations/main/#sessions-apis) section. See [Identify your Okta solution](https://help.okta.com/okta_help.htm?type=oie&id=ext-oie-version) to determine your Okta version.
 
 This guide provides examples for retrieving and setting a session cookie for different deployment scenarios. With these scenarios, you can provide SSO capabilities for custom web apps built on Okta.
 

@@ -96,7 +96,7 @@ The context object allows [trusted web applications](#trusted-application) such
 | ----------- | ----------------------------------------------------------------------------- | -------- | -------- | ------ | -------- | --------- |
 | deviceToken | A globally unique ID (without hyphens) identifying the user's client device or user agent | String   | TRUE     | FALSE  | FALSE    | 32          |
 
-> **Caution:** The `deviceToken` parameter isn't shared between the Authentication API and the Okta Identity Engine-specific APIs. See [Upgrade to Okta Identity Engine](https://developer.okta.com/docs/guides/oie-upgrade-overview/main/)>.
+> **Caution:** The `deviceToken` parameter isn't shared between the Authentication API and the Okta Identity Engine-specific APIs. See [Upgrade to Okta Identity Engine](https://developer.okta.com/docs/guides/oie-upgrade-overview/main/) and [Device token behavior changed](/docs/guides/oie-upgrade-api-changes/main/#device-token-behavior-changed).
 
 > **Note:**
 >
@@ -1487,6 +1487,8 @@ Only WS-Federation, SAML-based apps are supported.
 
 > **Note:** Okta Sign-on Policy and the related App Sign-on Policy are evaluated after successful primary authentication.
 
+> **Note:** In Identity Engine, the `audience` parameter isn't supported. See [Authentication API changes after the upgrade](/docs/guides/oie-upgrade-api-changes/main/#authentication-api-changes).
+
 
 ##### Request example for IdP-initiated step-up authentication
 
@@ -5698,6 +5700,8 @@ curl -v -X POST \
 
 ## Recovery operations
 
+> **Note:** In Identity Engine, custom recovery flows built on these operations have limitations. See [Password recovery limitations with the Classic Authentication API](/docs/guides/oie-upgrade-api-changes/main/#password-recovery-limitations-with-the-classic-authentication-api).
+
 ### Forgot password
 
 

@@ -576,6 +576,10 @@ export const guides = [
             title: "Identity Engine limitations",
             guideName: "ie-limitations",
           },
+          {
+            title: "Okta API changes for OIE",
+            guideName: "oie-upgrade-api-changes",
+          },
           {
             title: "Update your event hooks for Identity Engine",
             guideName: "oie-upgrade-event-hooks",