workos-node

@workos-inc/node is the official server-side client for the WorkOS API, giving Node and TypeScript applications a single typed entry point into WorkOS’s enterprise-readiness building blocks: SSO, Directory Sync (SCIM), User Management/AuthKit, Multi-Factor Auth, Audit Logs, Admin Portal, Feature Flags, and more. Rather than hand-rolling OAuth/SAML flows and SCIM parsing per customer, teams instantiate a single WorkOS client and call domain-scoped modules (workos.sso, workos.directorySync, workos.userManagement, …) that each map to a documented WorkOS API resource.

The SDK builds on the fetch API so it runs unmodified across Node, edge runtimes (Cloudflare Workers/workerd, Vercel Edge, Convex), and browser/mobile clients in a credential-less PKCE mode. It automatically retries transient failures (network errors, 408/429/5xx) with exponential backoff and jitter, honors Retry-After headers, and assigns idempotency keys to retried writes so a retried POST is never double-applied.

What You Get

• A single WorkOS client exposing typed sub-clients for every API domain: sso, directorySync, userManagement, organizations, auditLogs, multiFactorAuth, adminPortal, webhooks, featureFlags, vault, widgets, and more
• Built-in PKCE support for public clients (browser/mobile/CLI apps that can’t hold a secret), including getAuthorizationUrlWithPKCE and code-verifier exchange helpers
• Automatic transient-failure retries with exponential backoff, jitter, Retry-After support, and idempotency-key assignment on retried writes
• Multi-runtime builds (index.mjs/index.cjs for Node, index.worker.mjs/index.worker.cjs for Cloudflare Workers, edge-light, and Convex) selected automatically via package.json exports conditions
• Typed request/response interfaces and a structured exception hierarchy (UnauthorizedException, RateLimitExceededException, UnprocessableEntityException, OauthException, etc.) mapped from WorkOS HTTP status codes

Common Use Cases

• Adding enterprise SSO (SAML/OIDC) login to a B2B SaaS product without implementing each customer’s identity provider handshake directly
• Syncing customer HR/directory groups and users into your app via SCIM, keeping org membership in sync automatically
• Building a full AuthKit-based user management flow (sign-up, sign-in, MFA, session refresh) for a Node or edge-deployed app
• Verifying and consuming WorkOS webhooks for org/directory/user lifecycle events inside an existing Node backend
• Rendering a self-serve Admin Portal so enterprise customers can configure their own SSO/directory connections without support tickets

Under The Hood

Architecture The WorkOS class in src/workos.ts is the sole composition root: its constructor resolves an API key or client ID (from arguments or WORKOS_API_KEY/WORKOS_CLIENT_ID env vars), builds a FetchHttpClient bound to api.workos.com, and eagerly instantiates one client instance per domain (Agents, ApiKeys, Connect, DirectorySync, Organizations, SSO, Webhooks, UserManagement, Vault, Widgets, and roughly fifteen more) as readonly properties, each taking the parent WorkOS instance and delegating HTTP calls back through its shared get/post/put/patch/delete methods. A centralized handleHttpError translates HTTP status codes (401, 404, 409, 422, 429, plus OAuth/authentication-shaped error bodies) into a typed exception hierarchy under common/exceptions, so every domain module raises consistent, typed errors from one place rather than each reimplementing status-code branching. Domain modules are organized as sibling directories (sso/, directory-sync/, user-management/, audit-logs/, …) each with its own interfaces, serializers, and fixtures, giving a modular one-class-per-API-resource structure with no cross-module coupling beyond the shared client.

Tech Stack Written in TypeScript, built with tsdown into dual ESM/CJS bundles plus separate Cloudflare Workers/edge-light/Convex builds selected via package.json exports conditions, targeting Node >=22.11. The HTTP layer is a thin FetchHttpClient wrapper around the global fetch API (no axios/node-fetch dependency), with iron-webcrypto, jose, and uint8array-extras inlined directly into the bundle as pinned dependencies rather than left as external npm deps, avoiding version-skew issues for consumers. PKCE/session cryptography goes through a SubtleCryptoProvider built on the standard Web Crypto API, which is what makes the same code path work identically in Node, Workers, and edge runtimes.

Code Quality Extensive test coverage: fifty-plus *.spec.ts files sit alongside their implementation files (one per domain module, plus dedicated specs for the HTTP client, PKCE, and the package’s public barrel export), run with Jest against jest-fetch-mock-mocked responses. CI (GitHub Actions, matrixed across Node 22 and 24) runs Prettier, ESLint (via typescript-eslint), tsc --noEmit typechecking, a full build, and the test suite on every push and PR — a comprehensive, enforced quality gate rather than tests-only. Error handling is explicit and typed throughout (a dedicated exception class per HTTP-error shape) rather than swallowed or stringly-typed.

What Makes It Unique Rather than being a generic HTTP wrapper, the SDK’s value is in encoding WorkOS’s specific enterprise-identity domain model (SSO connections, directory groups/users, organization domains, admin portal sessions) as first-class typed objects, plus dual-mode operation: a secret-holding server client and a secret-less PKCE public client from the same package, letting one library cover both a Node backend and a browser/mobile/CLI frontend flow for the same WorkOS integration.