Migrate from the standalone SSO API

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 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:

import type { NextApiRequest, NextApiResponse } from 'next';
import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS(process.env.WORKOS_API_KEY);
const clientId = process.env.WORKOS_CLIENT_ID;

export default (_req: NextApiRequest, res: NextApiResponse) => {
  // The user's organization ID
  const organization = 'org_123';

  // The callback URI WorkOS should redirect to after the authentication
  const redirectURI = 'https://my-app.com/callback';

  const authorizationUrl = workos.sso.getAuthorizationURL({
    organization,
  const authorizationUrl = workos.userManagement.getAuthorizationUrl({
    organizationId: organization,
    redirectURI,
    clientId,
  });

  res.redirect(authorizationUrl);
};

const express = require('express');
const { WorkOS } = require('@workos-inc/node');

const app = express();

const workos = new WorkOS(process.env.WORKOS_API_KEY);
const clientId = process.env.WORKOS_CLIENT_ID;

app.get('/auth', (_req, res) => {
  // The user's organization ID
  const organization = 'org_123';

  // The callback URI WorkOS should redirect to after the authentication
  const redirectURI = 'https://my-app.com/callback';

  const authorizationUrl = workos.sso.getAuthorizationURL({
    organization,
  const authorizationUrl = workos.userManagement.getAuthorizationUrl({
    organizationId: organization,
    redirectURI,
    clientId,
  });

  res.redirect(authorizationUrl);
});

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:

import type { NextApiRequest, NextApiResponse } from 'next';
import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS(process.env.WORKOS_API_KEY);
const clientId = process.env.WORKOS_CLIENT_ID;

export default async (req: NextApiRequest, res: NextApiResponse) => {
  const { code } = req.query;

  const { profile } = await workos.sso.getProfileAndToken({
  const { user } = await workos.userManagement.authenticateWithCode({
    code,
    clientId,
  });

  // Use the information in `user` for further business logic.

  res.redirect('/');
};

const express = require('express');
const { WorkOS } = require('@workos-inc/node');

const app = express();
const workos = new WorkOS(process.env.WORKOS_API_KEY);
const clientId = process.env.WORKOS_CLIENT_ID;

app.get('/callback', async (req, res) => {
  const { code } = req.query;

  const { profile } = await workos.sso.getProfileAndToken({
  const { user } = await workos.userManagement.authenticateWithCode({
    code,
    clientId,
  });

  // Use the information in `profile` for further business logic.

  res.redirect('/');
});

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 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:

export default (_req: NextApiRequest, res: NextApiResponse) => {
  // The callback URI WorkOS should redirect to after the authentication
  const redirectURI = 'https://my-app.com/callback';

  const authorizationUrl = workos.userManagement.getAuthorizationUrl({
    provider: 'authkit',
    redirectURI,
    clientId,
  });

  res.redirect(authorizationUrl);
};

app.get('/auth', (_req, res) => {
  // The callback URI WorkOS should redirect to after the authentication
  const redirectURI = 'https://my-app.com/callback';

  const authorizationUrl = workos.userManagement.getAuthorizationUrl({
    provider: 'authkit',
    redirectURI,
    clientId,
  });

  res.redirect(authorizationUrl);
});

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.