WorkOS AuthKit

Resolve a verified WorkOS AuthKit user in TanStack Start without coupling authentication to vault-key recovery.

@ownfold/workos adapts the server context created by WorkOS AuthKit middleware to Ownfold’s stable user-ID resolver. It reads only the verified WorkOS user.id.

Install

pnpm add @ownfold/workos@beta @ownfold/server@beta @workos/authkit-tanstack-react-start

Configure TanStack Start

WorkOS AuthKit requires these host variables:

The SDK also accepts optional WORKOS_API_HOSTNAME, WORKOS_API_HTTPS, WORKOS_API_PORT, WORKOS_COOKIE_MAX_AGE, WORKOS_COOKIE_NAME, WORKOS_COOKIE_DOMAIN, and WORKOS_COOKIE_SAME_SITE overrides. Omit an override to retain the SDK default.

workosAuthKitUserResolver() validates all configured values with Ownfold’s internal T3 Env schema before it creates a resolver. WorkOS reads the same process variables. Applications only set the variables; they do not install or configure T3 Env or Valibot. Never place API keys or cookie passwords in client variables.

Install WorkOS authkitMiddleware() in the application before Ownfold handlers, then configure the resolver:

import { createVaultServer } from "@ownfold/server"
import { workosAuthKitUserResolver } from "@ownfold/workos/tanstack-start"
import { adapter } from "./vault-adapter"

export const vaultServer = createVaultServer({
  adapter,
  getUserId: workosAuthKitUserResolver(),
})

The resolver returns null only when AuthKit explicitly reports no user. Missing middleware, session-verification failures, and malformed authenticated users fail closed. It never accepts an identity from a header, query string, or request body and never substitutes email or organization membership for user.id.

Authentication is not vault recovery

WorkOS authentication answers which user owns the vault. It does not provide an Ownfold root key. Password reset or WorkOS passkey login still requires one of:

• a separate Ownfold passkey vault-access credential;
• an enrolled local Ownfold device;
• an Ownfold Recovery Kit; or
• approval from another enrolled Ownfold device.

Offer the separate Ownfold passkey credential as the primary new-browser path when PRF is supported. The local device, Recovery Kit, and pairing paths are fallbacks.

WorkOS currently performs passkey authentication in hosted AuthKit UI. That ceremony does not expose WebAuthn PRF output to the host application, so it cannot be reused to derive Ownfold key material.

See Passkey vault access for the separate PRF credential and new-browser enrollment flow.

Use a separate explicit resolver if organization ownership is required. The default adapter always uses per-user user.id ownership.