Ecosystem Overview
Seamless Auth is not a single package. It is a small ecosystem of projects that work together to deliver passwordless authentication, self-hosted infrastructure, and operator tooling.
This page is the fastest way to understand what each repository is for and where to start.
Mental Model
Section titled “Mental Model”seamless-cli -> scaffolds and checks your local stack
seamless-auth-api -> runs the auth engine
@seamless-auth/express, @seamless-auth/fastify, @seamless-auth/nextjs, or @seamless-auth/core(or seamless-auth for Python, seamless-auth-go for Go, seamless-auth for Rust) -> connects your backend to the auth engine
@seamless-auth/react, @seamless-auth/angular, @seamless-auth/vue, @seamless-auth/svelte, or@seamless-auth/react-native -> connects your web or mobile frontend to the auth flow
seamless-auth-admin-dashboard -> gives operators a UI for users, organizations, sessions, events, security, and configThe Main Pieces
Section titled “The Main Pieces”| Project | What it is | Use it when |
|---|---|---|
seamless-cli |
CLI for scaffolding and checking a local stack | You want a working project (React or Next.js web, Express or Fastify API, optional Expo app) with auth wired |
seamless-auth-api |
Self-hostable auth server | You need the passwordless auth engine itself |
@seamless-auth/core |
Framework-agnostic server auth primitives | You are building your own backend adapter |
@seamless-auth/express |
Official Express adapter | Your backend is Express (the most mature adapter path) |
@seamless-auth/fastify |
Official Fastify adapter | Your backend is Fastify (Server SDKs) |
@seamless-auth/nextjs |
Official Next.js App Router adapter | Your Next.js app is its own backend (Next.js) |
seamless-auth (PyPI) |
Official Python adapter | Your backend is FastAPI or Django (Python) |
seamless-auth-go |
Official Go adapter | Your backend is Go net/http, chi, Echo, or Gin (Go) |
seamless-auth (crates.io) |
Official Rust adapter | Your backend is Axum (Rust) |
@seamless-auth/react |
React SDK and built-in auth screens | Your frontend is React and you want a ready-to-use auth integration |
@seamless-auth/angular |
Angular service, guards, and built-in screens | Your frontend is Angular 20, 21, or 22 (Angular SDK) |
@seamless-auth/vue |
Vue plugin, composable, guards, and built-in screens | Your frontend is Vue 3.5 or later (Vue SDK) |
@seamless-auth/svelte |
Svelte session, SvelteKit guards, and built-in screens | Your frontend is Svelte 5 or SvelteKit (Svelte SDK) |
@seamless-auth/react-native |
React Native SDK: provider, hooks, native ports | Your frontend is an Expo or React Native app (React Native SDK) |
@seamless-auth/client |
The framework-free client and sign-in flows the SDKs share | You are building a binding for another framework (React SDK) |
seamless-auth-admin-dashboard |
Operator dashboard app | You want a UI for admins and support teams |
@seamless-auth/types |
Shared request/response and domain types | You want consistent types across apps and tooling |
How The Pieces Fit
Section titled “How The Pieces Fit”1. The Auth Server Is The Core
Section titled “1. The Auth Server Is The Core”seamless-auth-api owns the authentication domain:
- registration
- login
- OTP flows
- WebAuthn / passkeys
- magic links
- OAuth
- TOTP / MFA
- sessions
- organizations
- JWKS
- system configuration
- admin and internal metrics endpoints
Everything else either talks to it directly or sits on top of it.
2. Server SDKs Protect Your API
Section titled “2. Server SDKs Protect Your API”Your application backend normally sits between the browser and the auth server.
That backend layer:
- owns the security boundary for your app
- validates cookies
- enforces authorization
- talks to the auth server using service-to-service credentials
If you use Express, start with @seamless-auth/express; Fastify, @seamless-auth/fastify; a
Next.js App Router application, @seamless-auth/nextjs. For FastAPI or Django, Go, or Axum, use the
Python, Go, or Rust adapter. If
you need a different Node.js runtime, start with @seamless-auth/core.
3. Frontend SDKs Drive The User Flow
Section titled “3. Frontend SDKs Drive The User Flow”@seamless-auth/react wraps your app with auth state and ships built-in auth routes for:
- login
- passkey login
- email / phone OTP verification
- magic link verification
- OAuth login helpers
- organization helpers
- step-up helpers
- WebAuthn PRF helpers
- passkey registration
The SDK gives you auth state and flow helpers, but your app still owns routing, authorization, and product-specific UI decisions.
@seamless-auth/angular gives an Angular application the same state and flows as an injectable
service with signals and observables, functional route guards, and optional standalone screens that
match the React ones. See Angular SDK.
@seamless-auth/vue does the same for Vue: a plugin and a useSeamlessAuth() composable returning
read-only refs, vue-router guards, and the same screens as named routes. See
Vue SDK.
@seamless-auth/svelte gives a Svelte 5 application a session whose properties are runes,
SvelteKit load guards, and the same screens as components you mount at your routes. See
Svelte SDK.
@seamless-auth/react-native gives an Expo or React Native app the same state and headless client
over bearer transport, with native passkeys and the platform keystore behind ports. It ships no
screens. See React Native SDK.
4. The Admin Dashboard Is A Separate App
Section titled “4. The Admin Dashboard Is A Separate App”The admin dashboard is not built into the auth server. It is its own frontend application that talks to the auth API.
That separation matters because:
- you can deploy the auth server without the dashboard
- you can customize the dashboard independently
- operator workflows stay separate from your end-user app
5. The CLI Connects Everything
Section titled “5. The CLI Connects Everything”seamless-cli is the fastest way to get a working stack. It scaffolds a web app (React or a
full-stack Next.js app), an API (Express or Fastify) unless the web template serves /auth itself,
an optional Expo mobile app, the auth server in Docker or local mode, and an optional admin console.
It also includes check, verify, and admin commands against a running instance. The first admin
is the account registered with the owner email init asks for. The current ../seamless-cli source
does not ship deploy, destroy, or contributor workspace commands.
It is the easiest starting point if you want to learn the ecosystem through a working project rather than by assembling every piece manually.
Compatibility Matrix
Section titled “Compatibility Matrix”Versions and declared ranges of each package as of the v0.23.0 release, 2026-11-08: the npm
latest tag for npm packages, and the latest GitHub Release for seamless-auth-api and
seamless-auth-admin-dashboard. Ranges are read from the released package.json. Every package
and the auth API require Node.js 22 or later (engines.node is >=22), except the messaging
packages, which require Node.js 18 or later.
| Package | Latest release | Declares on other Seamless packages | Other peer ranges |
|---|---|---|---|
seamless-auth-api |
0.23.0 | @seamless-auth/types ^0.40.0, @seamless-auth/messaging, -aws, -twilio ^0.3.1 |
None |
@seamless-auth/oidc-provider |
0.4.1 | @seamless-auth/express and core ^0.26.0, @seamless-auth/types ^0.40.0 |
None |
@seamless-auth/core |
0.26.0 | @seamless-auth/types ^0.40.0 |
None |
@seamless-auth/express |
0.26.0 | @seamless-auth/core ^0.26.0 |
express >=5.0.0 |
@seamless-auth/fastify |
0.17.0 | @seamless-auth/core ^0.26.0 |
fastify >=5.0.0 |
@seamless-auth/nextjs |
0.10.0 | @seamless-auth/core ^0.26.0, @seamless-auth/types ^0.40.0 |
None |
@seamless-auth/client |
0.9.0 | @seamless-auth/types ^0.38.0 |
None |
@seamless-auth/react |
0.20.0 | @seamless-auth/client ^0.9.0, @seamless-auth/types ^0.38.0 |
react and react-dom 18 or 19, optional react-router-dom 6.4+ or 7.15.1+ |
@seamless-auth/angular |
0.5.0 | @seamless-auth/client ^0.9.0 |
@angular/core, common, router 20, 21, or 22, and rxjs 7 |
@seamless-auth/vue |
0.4.0 | @seamless-auth/client ^0.9.0 |
vue 3.5+, optional vue-router 4.4+ or 5 |
@seamless-auth/svelte |
0.4.0 | @seamless-auth/client ^0.9.0 |
svelte 5, optional @sveltejs/kit 2.26+ or 3 |
@seamless-auth/react-native |
0.5.0 | @seamless-auth/client ^0.9.0, @seamless-auth/types ^0.38.0 |
react 18 or 19 |
@seamless-auth/types |
0.40.0 | None | None |
@seamless-auth/messaging |
0.3.1 | @seamless-auth/types ^0.34.0 |
None |
@seamless-auth/messaging-aws |
0.3.1 | @seamless-auth/messaging ^0.3.1 |
None |
@seamless-auth/messaging-twilio |
0.3.1 | @seamless-auth/messaging ^0.3.1 |
None |
seamless-cli |
0.30.0 | @seamless-auth/types ^0.40.0 |
None |
seamless-auth-admin-dashboard |
0.14.0 | @seamless-auth/react ^0.19.0, @seamless-auth/types ^0.40.0 |
None |
How to read it:
- Everything is still 0.x, and a caret range on a 0.x version pins the minor:
^0.20.0accepts 0.20.x but not 0.21.0. A package moves to a new minor of a dependency only when its own range is bumped and released. @seamless-auth/express,fastify, andnextjsdeclare@seamless-auth/coreasworkspace:^, which pnpm rewrites at publish to a caret on the core version in the same release (^0.26.0today).@seamless-auth/typesis split across three minors. The auth API,oidc-provider,core,nextjs, the CLI and the dashboard declare ^0.40.0.client,reactandreact-nativedeclare ^0.38.0, and the messaging packages ^0.34.0. An app that installs packages from more than one group gets more than one copy of it.@seamless-auth/oidc-provider0.4.0 and 0.4.1 speak OpenID Provider contract version 3, as auth API 0.22.0 and 0.23.0 do. Run 0.4.1 with native or desktop clients: on 0.4.0 a step-up or second sign-in shares the first sign-in’s grant, so revoking the replaced refresh token ends both. Itspermissionsandcustom_claimsscopes need auth API 0.23.0; against 0.22.0 those claims are not released.- The adapters’ permission guards (
requirePermissionand the framework equivalents) need auth API 0.23.0. Against an older API they deny every request, since no token carries permissions. - The messaging packages are used by
seamless-auth-apito deliver email and SMS. Your application does not install them. - The auth API exposes an HTTP contract, not a package range. No package declares a range on
seamless-auth-api, so pair the API and the server SDK from the same release window. - Auth API 0.23.0 streams audit events over OTLP only. Syslog sinks arrive in 0.23.1 (How To Stream Audit Events To A SIEM).
Python, Go, And Rust Adapters
Section titled “Python, Go, And Rust Adapters”These are not npm packages, so they sit outside the table above and npm run check:matrix. Each
declares no range on another Seamless package; it reads the auth API’s adapter manifest at runtime
instead.
| Adapter | Latest release | Registry | Needs |
|---|---|---|---|
seamless-auth (Python) |
0.6.0 | PyPI | Python 3.11+, FastAPI 0.115+ or Django 5.2+, auth API v0.18.0+ (permission guards: v0.23.0+) |
github.com/fells-code/seamless-auth-go |
v0.6.0 | Go module proxy (tag v0.6.0) |
Go 1.22+, auth API v0.18.0+ (permission guards: v0.23.0+) |
seamless-auth (Rust) |
0.6.0 | crates.io | Rust 1.88+, Axum 0.8, auth API v0.18.0+ (permission guards: v0.23.0+) |
What The CLI Scaffolds
Section titled “What The CLI Scaffolds”seamless-cli 0.30.0 does not install the newest of everything. It pins the images and the
template tag it scaffolds, so a given CLI version always produces the same project:
What seamless init uses |
Pinned to | Where it is set |
|---|---|---|
| Auth API image | ghcr.io/fells-code/seamless-auth-api:v0.23.0 |
seamless-cli src/core/images.ts |
| Admin dashboard image | ghcr.io/fells-code/seamless-auth-admin-dashboard:v0.14.0 |
seamless-cli src/core/images.ts |
| Starter templates | fells-code/seamless-templates at v0.22.0 |
seamless-cli src/core/images.ts |
| Express API template | @seamless-auth/express ^0.25.0 |
templates/api/express/package.json |
| Fastify API template | @seamless-auth/fastify ^0.16.0 |
templates/api/fastify/package.json |
| Next.js template | @seamless-auth/nextjs ^0.9.0, @seamless-auth/react ^0.20.0 |
templates/fullstack/nextjs/package.json |
| React web templates | @seamless-auth/react ^0.20.0 |
templates/web/react-vite, templates/web/react-oauth |
| Angular web template | @seamless-auth/angular ^0.5.0 |
templates/web/angular/package.json |
| Vue web template | @seamless-auth/vue ^0.4.0 |
templates/web/vue/package.json |
| SvelteKit web template | @seamless-auth/svelte ^0.4.0 |
templates/web/svelte/package.json |
| Expo template | @seamless-auth/react-native ^0.5.0 |
templates/mobile/expo/package.json |
| Gin API template | github.com/fells-code/seamless-auth-go v0.6.0 |
templates/api/gin/go.mod |
| Axum API template | seamless-auth 0.6 |
templates/api/axum/Cargo.toml |
| FastAPI API template | seamless-auth[fastapi]>=0.6,<0.7 |
templates/api/fastapi/pyproject.toml |
Template paths are inside fells-code/seamless-templates at v0.22.0. The Express, Fastify and
Next.js templates are one minor behind the server adapters released with v0.23.0, so a new project
gets verifyWebhook (@seamless-auth/core/webhook, core 0.26.0) only after its adapter range moves
to the 0.26 line (0.17 for Fastify, 0.10 for Next.js).
Keeping This Matrix Current
Section titled “Keeping This Matrix Current”Update this section in the same change that documents a release:
- For each package published, set its version from its
package.jsononmainand update every range that points at it (dependenciesandpeerDependencies). - When
seamless-clichangesSEAMLESS_AUTH_API_VERSION,SEAMLESS_AUTH_ADMIN_DASHBOARD_VERSION, orSEAMLESS_TEMPLATES_REFinsrc/core/images.ts, update the scaffold table and re-read the template ranges at the new tag. - Change the date at the top of the section, then run
npm run check:matrix.
npm run check:matrix (scripts/check-compat-matrix.mjs) reads the table above and compares each
“Latest release” with what is actually released: npm view <package> version for the npm packages, and
the latest GitHub release tag for seamless-auth-api and seamless-auth-admin-dashboard, which are
not published to npm. It prints ok or drift per row and exits 1 on any drift or on an npm
package it cannot look up. A GitHub row it cannot read (for example over the unauthenticated rate
limit) is skipped with a note. It needs the network, so it is not part of npm run lint. The
check-compat-matrix workflow runs it every Monday and on demand (workflow_dispatch), so a failed
run means a release has outpaced this table.
Choose Your Starting Point
Section titled “Choose Your Starting Point”I want a working stack quickly
Section titled “I want a working stack quickly”Start with Getting Started and CLI Overview.
I want to self-host the auth engine
Section titled “I want to self-host the auth engine”Read Auth API.
I need to integrate my backend
Section titled “I need to integrate my backend”Read Server SDKs and How To Secure Routes.
I need to integrate my React app
Section titled “I need to integrate my React app”Read React SDK and How To Build Your Own Auth UI.
I need to integrate a mobile app
Section titled “I need to integrate a mobile app”Read React Native SDK and Mobile Passkeys.
seamless init --mobile=expo scaffolds an Expo app next to the web and API projects.
I need OAuth, teams, or MFA
Section titled “I need OAuth, teams, or MFA”Read How To Add OAuth Login, How To Use Organizations And Memberships, How To Use Roles And Permissions, and How To Use TOTP And Step-Up.
I need an operator UI
Section titled “I need an operator UI”Read Admin Dashboard.
What This Docs Site Is Becoming
Section titled “What This Docs Site Is Becoming”The docs are being reshaped around this ecosystem model:
Startfor guided onboardingBuildfor package and integration docsUnderstandfor concepts and system behaviorOperatefor CLI and runtime workflowsReferencefor exact routes, env vars, and technical contracts
If a page makes a claim about a package or command, it should line up with the source repository for that package or command.
Next Step
Section titled “Next Step”→ Continue to Auth API