WorkOS

WorkOS is a hosted identity service built for apps that sell to companies, with single sign-on and directory sync for your customers' organisations. Behind auth, it holds your users while your routes keep one way to read the session and require a role. Pick WorkOS when enterprise customers are your main audience and you want their SSO connections managed by a provider.

auth:
  driver: workos

Before you start

You need a WorkOS account.

1. Use separate environments. WorkOS gives you a staging and a production environment, each with its own keys.
2. Copy the API key and client ID for each environment.
3. Add your redirect URIs: the route that receives WorkOS's redirect after sign-in. The path MainSDK mounts is not defined yet.

Configure

auth:
  driver: workos
  methods: [passkeys, sso]
  sso: { protocols: [saml, oidc], scim: true }
  # [to be decided] key names; suggested secrets: WORKOS_API_KEY, WORKOS_CLIENT_ID

The auth spec does not define the driver's credential keys yet; they take secret: references when it does.

Use it

import { auth } from "mainsdk";

export async function POST(req: Request) {
  const { email } = await req.json();
  return auth.sso.signIn(req, { email });   // routes by verified email domain
}

Local development and testing

Use the local auth driver in development and WorkOS's staging environment to try real SSO. In tests, createTestApp() from @mainsdk/testing runs auth on its in-memory fake, and chaos.on("auth", { outage: true }) checks that auth.require() fails closed.

What MainSDK adds on top

• Short-lived, device-bound sessions with rotating refresh tokens.
• Passkeys by default, phishing-resistant.
• Fails closed when WorkOS cannot be reached.
• SAML assertions checked for signature, audience and replay (MAIN-AUTH-0008); OIDC state and nonce checked (MAIN-AUTH-0007).

See Sign-in and sessions.

Limits and notes

• The WorkOS driver and its capability profile have a ticket in the auth spec next to Auth0.
• Users stay in your WorkOS environment (byo-identity). Check where WorkOS stores data against your residency needs.
• auth.raw() returns the WorkOS client; mainsdk check lists every use.

Swap to or from it

auth:
  driver: auth0   # was workos

FAQ

Is this SSO for the MainSDK console? No. This driver signs your app's users in. Console SSO is a separate MainSDK Cloud feature.

Do I need WorkOS to offer SSO? No. MainSDK provides SAML and SCIM in your app on top of any driver that lacks them.

Next

• Sign-in and sessions
• Auth0 and Clerk
• Swap a driver

Open questions