@modfolio/connect-sdk

Modfolio Connect SSO/OIDC SDK for ecosystem apps. v7.3.0.

Install

bun add @modfolio/connect-sdk

Published to public npm — no token or .npmrc needed. (A legacy GitHub Packages mirror still exists; using it requires @modfolio:registry=https://npm.pkg.github.com plus a GitHub Packages token, but new apps should use public npm.)

Quick Start (SvelteKit)

// src/lib/server/auth.ts
import { createSvelteKitAuth } from "@modfolio/connect-sdk/sveltekit";

export const auth = createSvelteKitAuth({
  clientId: "your-app-name",
});

// src/hooks.server.ts
import { auth } from "$lib/server/auth";
export const handle = auth.handle;

// src/routes/auth/login/+server.ts
export const GET = auth.loginHandler;

// src/routes/auth/callback/+server.ts
export const GET = auth.callbackHandler;

// src/routes/auth/logout/+server.ts
export const GET = auth.logoutHandler;

Adapters

| Framework | Import | Factory | |-----------|--------|---------| | SvelteKit 5 | @modfolio/connect-sdk/sveltekit | createSvelteKitAuth() | | Astro | @modfolio/connect-sdk/astro | createAstroAuth() | | SolidStart | @modfolio/connect-sdk/solidstart | createSolidStartAuth() | | Nuxt 3 | @modfolio/connect-sdk/nuxt | createNuxtAuth() | | Next.js | @modfolio/connect-sdk/nextjs | createNextAuth() (App + Pages Router) | | Qwik | @modfolio/connect-sdk/qwik | createQwikAuth() | | Hono (CF Workers) | @modfolio/connect-sdk/hono | createHonoAuth() |

Utility export paths: ./ssf (CAEP receiver) · ./dpop · ./fedcm · ./agent (MCP) · ./management · ./management-client.

Management API (PAT)

Programmatic app management with a Personal Access Token (mfp_…, issued at account.modfolio.io/developers/tokens). Two equivalent surfaces:

// Typed client — request/response types generated from the OpenAPI spec
import { createManagementClient } from "@modfolio/connect-sdk/management-client";

const connect = createManagementClient({ token: process.env.MODFOLIO_PAT! });
const { client_id } = await connect.createClient({
  name: "My App",
  redirect_uris: ["https://myapp.com/auth/callback"],
});

// Function helpers — same wire calls, handwritten types
import { registerApp, whoami } from "@modfolio/connect-sdk/management";

Methods: whoami · listClients · getClient · createClient · renameClient · deleteClient · addRedirectUri · removeRedirectUri · getScopes. Non-2xx responses throw ManagementError (.status, .code).

The types in src/generated/ are rendered from docs/openapi.json by bun run docs:openapi (repo root) and kept byte-fresh by the openapi:drift quality gate — never edit them by hand.

Defaults

| Config | Default | Purpose | |--------|---------|---------| | connectUrl | https://login.modfolio.io | OIDC API | | loginUrl | https://login.modfolio.io | Login UI redirect | | issuer | https://connect.modfolio.io | JWT issuer verification | | sessionCookie | mc_session | Session cookie name | | scope | openid profile email | OIDC scopes |

Flow

1. App /auth/login redirects to https://login.modfolio.io/{clientId} with PKCE S256
2. User authenticates on hosted login page
3. Login redirects to app /auth/callback with code + state
4. SDK exchanges code at POST /sso/token
5. SDK verifies JWT (issuer: https://connect.modfolio.io) and sets session cookie

Full Guide

See docs/sdk-integration-guide.md for:

• All 5 framework examples with complete route setup
• ConnectUser type reference
• Utility functions (MFA, org, tenant, ReBAC, webhooks)
• Local dev port assignments (22 apps)
• CF Pages build configuration

Upgrade notes:

• docs/sdk-v4-upgrade.md covers the v3 to v4 tenant-aware changes.