Public API

Client

import { Client } from "./src/stytch/index";

const client = new Client({
  project_id: process.env.STYTCH_PROJECT_ID!,
  secret: process.env.STYTCH_SECRET!,
});

The B2C client. Instantiate once at server startup. Exposes sub-clients for every B2C product: client.magicLinks, client.sessions, client.oauth, client.otps, client.passwords, client.m2m, client.totps, client.cryptoWallets, etc. All methods return promises.

B2BClient

import { B2BClient } from "./src/stytch/index";

const b2bClient = new B2BClient({
  project_id: process.env.STYTCH_PROJECT_ID!,
  secret: process.env.STYTCH_SECRET!,
});

The B2B client for organization-centric auth. Exposes b2bClient.organizations, b2bClient.members, b2bClient.sessions, b2bClient.sso, b2bClient.scim, b2bClient.rbac, b2bClient.magicLinks, b2bClient.passwords, b2bClient.discovery, b2bClient.mfa, and more. Use this when your product has multi-tenant org structures.

SamlShieldClient

import { SamlShieldClient } from "./src/stytch/index";

const samlShield = new SamlShieldClient({
  public_token: "public-token-live-xxxx",
});

A lightweight standalone client for validating SAML responses via Stytch's SAML Shield product. It does not require a secret key—only your public token. Use the samlShield.samlshield.validate({ SAMLResponse: "..." }) method to verify base64-encoded SAML responses from an IdP.

Working examples

Scenario - Send a B2C magic link and authenticate the token

A user enters their email; your API sends a magic link, then authenticates the token when the user clicks it.

import { Client } from "./src/stytch/index";

const client = new Client({
  project_id: process.env.STYTCH_PROJECT_ID!,
  secret: process.env.STYTCH_SECRET!,
});

// Send magic link
async function sendMagicLink(email: string): Promise<void> {
  const res = await client.magicLinks.email.loginOrCreate({
    email,
    login_magic_link_url: "https://example.com/authenticate",
    signup_magic_link_url: "https://example.com/authenticate",
  });
  console.log("Magic link sent, user_id:", res.user_id);
}

// Authenticate token from clicked link
async function authenticateToken(token: string): Promise<void> {
  const res = await client.magicLinks.authenticate({ token });
  console.log("Authenticated session token:", res.session_token);
}

Scenario - B2B organization creation and member magic link login

An admin creates an org; a member logs in via magic link scoped to that org.

import { B2BClient } from "./src/stytch/index";

const client = new B2BClient({
  project_id: process.env.STYTCH_PROJECT_ID!,
  secret: process.env.STYTCH_SECRET!,
});

async function setupOrg(): Promise<string> {
  const org = await client.organizations.create({
    organization_name: "Acme Co",
    organization_slug: "acme-co",
    email_allowed_domains: ["acme.co"],
  });
  console.log("Created org:", org.organization.organization_id);
  return org.organization.organization_id;
}

async function sendB2BMagicLink(
  organizationId: string,
  emailAddress: string
): Promise<void> {
  await client.magicLinks.email.loginOrSignup({
    organization_id: organizationId,
    email_address: emailAddress,
    login_redirect_url: "https://example.com/authenticate",
    signup_redirect_url: "https://example.com/authenticate",
  });
}

Scenario - Validate a SAML response with SAML Shield

An SP-initiated SSO flow receives a SAML response from an IdP. Before processing, validate it through Stytch SAML Shield.

import { SamlShieldClient } from "./src/stytch/index";

const samlShield = new SamlShieldClient({
  public_token: process.env.STYTCH_PUBLIC_TOKEN!,
});

async function validateSamlResponse(samlResponseBase64: string): Promise<void> {
  const result = await samlShield.samlshield.validate({
    SAMLResponse: samlResponseBase64,
  });
  if (result.status_code === 200) {
    console.log("SAML response is valid:", result.message);
  } else {
    throw new Error(`SAML validation failed: ${result.message}`);
  }
}

File walkthrough

• index.ts - Barrel file; re-exports all B2B, B2C, samlshield, shared errors, and environment utilities. The single import point for downstream code.
• b2b/client.ts - B2BClient class constructor; wires all B2B sub-clients together.
• b2b/index.ts - Re-exports all B2B types (requests, responses, models) for external consumers.
• b2b/organizations.ts / b2b/organizations_members.ts - Organization and member CRUD operations.
• b2b/sessions.ts - B2B session authenticate, revoke, JWT-local verification.
• b2b/sso.ts / b2b/sso_saml.ts / b2b/sso_oidc.ts - SSO connection management and authentication.
• b2b/scim.ts / b2b/scim_connection.ts - SCIM provisioning connection lifecycle.
• b2b/rbac.ts / b2b/rbac_local.ts - RBAC policy fetching and local authorization checks.
• b2b/passwords.ts / b2b/magic_links.ts / b2b/otp_sms.ts / b2b/totps.ts - B2B authentication factor modules.
• b2b/discovery.ts - Discovered organizations and intermediate session flows.
• b2c/client.ts - Client class constructor; wires all B2C sub-clients.
• b2c/index.ts - Re-exports all B2C types.
• b2c/m2m.ts / b2c/m2m_clients.ts - Machine-to-machine client management and token authentication.
• b2c/fraud.ts / b2c/fraud_fingerprint.ts / b2c/fraud_rules.ts - Device fingerprinting and fraud detection.
• b2c/sessions.ts - B2C session authenticate and JWT-local verification.
• b2c/connected_apps.ts - OAuth connected app management.
• samlshield/index.ts - SamlShieldClient and SamlShield class; SAML response HTTP validation.
• shared/index.ts - Core request() function, fetchConfig type, HTTP wiring via undici.
• shared/errors.ts - StytchError, RequestError, StytchErrorJSON exported for error handling.
• shared/envs.ts - Environment constants (API base URLs for live/test).

Common pitfalls and fixes

• Wrong import path after copying source: If you alias stytch in tsconfig.paths, ensure the alias points to index.ts, not the b2b/ or b2c/ sub-directories directly.
• jose version mismatch: This SDK requires jose v4+; older projects pinned to jose@2 will break JWT verification—run npm install jose@latest.
• undici not found in Next.js edge runtime: The undici Dispatcher type and runtime are Node.js-only; do not import this SDK in Next.js edge middleware. Use it only in API routes or server actions with runtime = "nodejs".
• Missing STYTCH_PROJECT_ID / STYTCH_SECRET at startup: The client constructor will throw or silently fail on first request—validate env vars explicitly before instantiating.
• ESM/CJS interop: The source uses export * and export default together; if bundling with CommonJS, set "esModuleInterop": true and "allowSyntheticDefaultImports": true in tsconfig.json.
• StytchError not caught separately: API errors from Stytch return a StytchError instance (not a plain Error); import it from source/shared/errors and use instanceof StytchError to read error_type and error_message fields.

Vibe-coding prompt template

I have copied the Stytch Node.js SDK source (upstream package: user@example.com) into
my project at `src/stytch/`. The integration guide is in `USAGE.md`.

Please help me integrate Stytch authentication into my project step by step:

1. Read `USAGE.md` and `src/stytch/index.ts` to understand available exports.
2. Instantiate `Client` (B2C) or `B2BClient` (B2B) using environment variables
   STYTCH_PROJECT_ID and STYTCH_SECRET.
3. Add the following feature to my project: [DESCRIBE YOUR USE CASE HERE, e.g.,
   "email magic link login for B2C users", "B2B SSO with SAML", "M2M token auth"].
4. Import only from `src/stytch/index.ts`. Do not install the npm `stytch` package.
5. Handle `StytchError` from `src/stytch/shared/errors.ts` for API errors.
6. Show the full TypeScript code, including Express/Next.js route handlers if applicable.

License and credit

The upstream license is MIT - see source/LICENSE if present, or refer to the stytch npm package and Stytch GitHub repository for the authoritative license text. Upstream package: user@example.com by Stytch, Inc.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.