<iframe src="https://www.googletagmanager.com/ns.html?id=GTM-M74D8PB" height="0" width="0" style="display:none;visibility:hidden">
Loading
Skip to NavigationSkip to Main Content
System Status
Announcements
Announcements
Search
Search
Select Language
Knowledge Base
Knowledge Articles
Support Videos ↗
Documentation
Product Documentation ↗
Developer Documentation ↗
Product Release Notes ↗
Community
Events & Webinars
Okta Ideas ↗
Resources
Product Hub
Customer Success Hub
Product Release Update
Learning
Okta Learning ↗
Get Support
Open a Case
HomeKnowledge Base

Deployment Model - Embedded API

Last Updated:

Administration

Telemetry detected a custom sign-in experience using the Okta /authn API (CUSTOMER_HOSTED_AUTHN_API) is actively in use. No changes are required to proceed with the upgrade. The /authn API will continue to operate in classic mode post-upgrade. To take advantage of Okta Identity Engine sign-in capabilities, the integration must be migrated to an OIE SDK or the Redirect model.

What this means for the upgrade: The upgrade can proceed without modifying the existing API integration. Post-upgrade, /authn API flows continue in classic mode. New OIE sign-in capabilities — including application sign-on policies, passwordless, and Direct Authentication — will not be available until the integration is migrated.

Applies To

  • CUSTOMER_HOSTED_AUTHN_API
  • Upgrade Eligibility: Eligible with Warning

The warning reflects the effort required to adopt OIE functionality post-upgrade. The upgrade itself can proceed without changes to the API integration.

Experience Impact

The org uses a custom sign-in experience that calls the Okta /authn API directly — for example, a server-side authentication proxy, API gateway, or custom login application. After upgrading to Identity Engine, the /authn API remains functional but continues on the Classic Authentication Pipeline.

Specific known gap — setCookieAndRedirect with sessionToken: If the integration passes a sessionToken to /login/sessionCookieRedirect?token=[SessionToken] after authenticating via /authn, this flow will not support OIE application sign-on policies post-upgrade. The Global Session Policy still applies, but application-level sign-on policies will not be enforced for these flows.

Additional areas requiring verification before upgrading:

  • Account Activation flow — Email templates with fromURI routing back to the custom application should be tested post-upgrade. Confirm whether the activation payload passes an activationToken into the custom /authn API flow, and whether any custom or external email is in use. See Activation Templates.
  • Custom Password Recovery — If recovery flows pass a recoveryToken to the /authn API, end-to-end testing is recommended before upgrading. See Recovery Templates.
  • Sessions API usage — Direct usage of the Sessions API should be reviewed for post-upgrade compatibility.
  • audience parameter — The audience parameter is not supported in OIE /authn API calls and must be removed.

Before the Upgrade

No changes are required to the /authn API integration prior to upgrading. Verify Account Activation and Recovery email templates, Custom Password Recovery flows, and audience parameter usage in an OIE preview environment before upgrading production.

  • Test Account Activation and Recovery email templates for fromURI redirects that target the custom sign-in application.
  • Test any Custom Password Recovery flows that pass a recoveryToken to the /authn API.
  • Remove any use of the audience parameter from /authn API calls.

After the Upgrade

Post-Upgrade Warning — “Remember My Device” behavior: If users have opted in to Remember this device or Don't prompt me again on this device, this behavior can be impacted when authentication policies are updated post-upgrade. Changes to policy rules — such as new factor requirements or updated reauthentication intervals — can invalidate saved device state and prompt users unexpectedly.

Moving to the Okta Hosted Sign-in experience (federation model) is highly recommended to ensure authentication policy changes are handled consistently and to deliver the best end-user experience across the full authentication flow.

When ready to unlock OIE features for this sign-in experience, choose one of the following paths:

  • Option 1: Shift to the Okta Hosted Sign-in Experience (Recommended) — Moving to the federation model that leverages the Okta Hosted Sign-in framework is highly recommended to optimize the user experience and get the most out of the OIE authentication flow. The Okta Sign-In Widget v3 provides significant extensibility for sign-in page customization without requiring a self-hosted integration.

  • Option 2: Migrate to an Embedded OIE SDK — Replace the /authn API calls with the OIE-compatible SDK for your language or framework, retaining the embedded sign-in experience while unlocking OIE features.

  • Option 3: Adopt the Direct Authentication API — For native or server-side flows, the Direct Authentication API is the modern replacement for the Classic /authn API.

For a detailed overview of migration paths, see Okta deployment models — redirect vs. embedded.

Related References

Recommended content

Still looking for help?
Loading
Okta Support - Deployment Model - Embedded API