WorkOS Docs Homepage
DashboardSign In

Migrate from the standalone SSO API

Learn how to migrate your code from an existing WorkOS SSO integration.

The WorkOS User Management API supports all of the same social and enterprise identity providers, while providing higher level authentication features that most applications need. In this guide, we’ll outline the steps to migrate an existing WorkOS SSO integration to the User Management API.

The existing standalone WorkOS SSO API will continue to be supported. This is a viable option for you if you prefer to handle more of the authentication flow yourself.

The primary difference between existing integrations with SSO or Directory Sync is the addition of a new resource: Users.

The WorkOS User object represents a single user in your application, and binds together information from all of the Directory and Identity providers that WorkOS supports into a single resource. As you migrate your existing integration, you can expect to replace references to WorkOS Profiles and Directory Users with instead references to Users.

If you have built an integration with our standalone SSO API using Get Authorization URL, you will need to switch these calls with analogous calls to the User Management API.

When initiating SSO for one of your users, instead of calling the SSO Get Authorization URL API, call the User Management Get Authorization URL API instead:


The User Management Get Authorization API supports all of the same initiation parameters as the old API. In addition, it also supports an additional provider type, authkit, which will be covered later in this guide.

Similar to an SSO integration, your application will still have a callback identified by the Redirect URI passed during the previous initiation call. The contract with your callback is the same, where you should expect to be given a code, along with any state that was originally provided.

However, instead of calling the SSO Get a Profile and Token API, call the User Management Authenticate API instead, with the grant_type set to authorization_code:


Important: Instead of receiving a Profile, your application now receives a full User object. While many of the fields are similar, such as the user’s email or name, the User ID’s will be different than the Profile ID’s you may have previously persisted in your application.

If email is a unique identifier in your application, you can use the WorkOS User’s email to identify the application-local user. WorkOS ensures that user email is verified before successfully completing an authentication request. When the API issues an email verification challenge, an email verification response is returned.

The User Management API offers a higher-level abstraction than the SSO API, offering more advanced security features like email verification and account Linking.

This means that when your application attempts to exchange a code for a user object, it may return one of several new expected errors. These map to cases that were previously mentioned, like requiring that the user first verify their email, or enroll in MFA.

If your application doesn’t require these extra settings, they can be disabled in the Authentication section of the WorkOS Dashboard.

If you are using AuthKit, you won’t need to handle error cases like required email verification, as AuthKit will automatically request this before a user is directed to their callback endpoint.

If you prefer to have full control over the authentication UI, you can choose to integrate with the User Management API directly. However, the easiest way to get started is to use AuthKit, a pre-built hosted authentication UI that supports guiding users through all of the advanced flows, like email verification, MFA enrollment + verification, and identity linking.

You can enable AuthKit from the WorkOS dashboard, where you can also configure AuthKit branding and custom domains.

Getting started with AuthKit is as simple as passing authkit as the provider:


AuthKit can handle many of the concerns your application likely needed to previously, such as identifying which users sign in using enterprise SSO, and correctly routing them to their organization’s identity provider.

Support for Directory Sync in User Management is coming soon, and this guide will be updated once it is generally available.

Check out the full guide, along with the API reference to get an idea of all the ways your application’s user management needs can be solved by WorkOS.

If you need help migrating your existing WorkOS integration, or have any other questions, please reach out to WorkOS support.