WorkOS Integration

Use WorkOS for B2B authentication when AuthKit, enterprise SSO, and organization-aware sessions should sit behind Farm-owned routes.

This adapter covers AuthKit sign-in and sealed sessions. Directory Sync and other WorkOS APIs remain separate application integrations.

Add WorkOS

farm add integration workos --ui

Configure

import { workos } from "@farm.js/integrations/workos";export const appIntegrations = {  auth: workos({    clientId: process.env.WORKOS_CLIENT_ID,    apiKey: process.env.WORKOS_API_KEY,    cookiePassword: process.env.WORKOS_COOKIE_PASSWORD,    callbackPath: "/callback",    protectedRoutes: ["/dashboard(.*)"],  }),} as const;export type AppIntegrations = typeof appIntegrations;

Farm builds the absolute redirect URI from the incoming request origin and callbackPath. Register that exact URL in WorkOS, for example https://app.example.com/callback.

Environment variables

Development has a local fallback cookie password. Production startup fails without an explicit password.

Choose SDK ownership

Let Farm construct WorkOS

The configuration above is the default path. When instance is omitted, Farm constructs one WorkOS client from clientId and apiKey, supplied directly or through environment variables.

Provide an application-owned instance

Pass a configured SDK through instance when the app needs WorkOS constructor options that Farm does not own. Farm uses the instance directly, so apiKey is no longer required by the integration. The AuthKit client ID can come from the instance, while the cookie password remains required because Farm owns the sealed session cookie.

When both are present, the supplied instance wins. Integration-owned route, cookie, and protection options still belong in workos(...).

import { WorkOS } from "@workos-inc/node";import { workos } from "@farm.js/integrations/workos";const workosClient = new WorkOS({  apiKey: process.env.WORKOS_API_KEY,  clientId: process.env.WORKOS_CLIENT_ID,});export const auth = workos({  instance: workosClient,  cookiePassword: process.env.WORKOS_COOKIE_PASSWORD,  protectedRoutes: ["/dashboard(.*)"],});

Routes and methods

Override these routes with loginPath, signUpPath, callbackPath, logoutPath, and sessionPath.

Start an AuthKit flow

Document navigation redirects directly:

<a href="/login?returnTo=/dashboard">Sign in</a><a href="/signup?returnTo=/dashboard">Create account</a>

The typed client returns the provider URL:

const result = await apiClient.auth.login.get({  query: {    returnTo: "/dashboard",  },});if (result.data) {  window.location.assign(result.data.redirectTo);}

Read the sealed session

const result = await api.auth.session.get();if (result.error && "status" in result.error && result.error.status === 401) {  // No authenticated WorkOS session.}const organizationId = result.data?.organizationId;const user = result.data?.user;

An authenticated response contains:

{  authenticated: true;  sessionId?: string;  organizationId?: string;  user: {    id: string;    email: string;    firstName?: string | null;    lastName?: string | null;    profilePictureUrl?: string | null;  };}

The organization ID is useful for looking up your app's tenant record. Authorization roles and permissions still need to be resolved by your application.

Logout

const result = await apiClient.auth.logout.post();if (result.data) {  window.location.assign(result.data.redirectTo);}

Farm clears the local cookie first. If a sealed session exists, WorkOS supplies the final logout URL; otherwise the user returns to the app origin.

Protect app routes

workos({  protectedRoutes: ["/dashboard(.*)", "/settings(.*)"],});

Signed-out requests receive a 307 redirect to /login with the original root-relative path in returnTo.

Options

Production checklist

• Register the production callback URL in WorkOS.
• Use a strong WORKOS_COOKIE_PASSWORD.
• Confirm the public request origin is preserved by your proxy.
• Test personal and organization-backed sessions.
• Map organizationId to an application tenant before authorizing tenant data.