Server SDKs and Adapters
Seamless Auth currently ships four official Node.js server-side packages:
@seamless-auth/core@seamless-auth/express@seamless-auth/fastify@seamless-auth/nextjs
These packages help your backend become the browser-facing security boundary between your app and the private auth server.
Backends in other languages have official adapters too, each with its own page:
- Python:
seamless-authon PyPI, for FastAPI and Django (Python) - Go:
github.com/fells-code/seamless-auth-go, fornet/http, chi, Echo, and Gin (Go) - Rust:
seamless-authon crates.io, for Axum (Rust)
Which One Should You Use?
Section titled “Which One Should You Use?”| Package | Use it when | What it gives you |
|---|---|---|
@seamless-auth/express |
Your backend is Express | Mounted auth routes, middleware, role guards; the most mature adapter |
@seamless-auth/fastify |
Your backend is Fastify | The Express adapter’s routes and cookies as a Fastify plugin |
@seamless-auth/nextjs |
Your Next.js App Router app is its own backend | Serves /auth from a route handler, reads the session in server components and proxy.ts (Next.js) |
@seamless-auth/core |
You need a custom adapter or framework integration | Framework-agnostic auth, cookie, OAuth, and role primitives |
seamless-auth (PyPI) |
Your backend is FastAPI or Django | Auth router or URLconf, RequireUser and require_auth guards (Python) |
seamless-auth-go |
Your backend is Go: net/http, chi, Echo, or Gin |
Handler() for /auth, RequireAuth middleware (Go) |
seamless-auth (crates) |
Your backend is Axum | router() for /auth, require_auth() layer, User extractor (Rust) |
If you already run Express, start with @seamless-auth/express. For Next.js, follow the
Next.js guide.
What The Backend Layer Does
Section titled “What The Backend Layer Does”Your backend integration layer is responsible for:
- receiving browser requests
- owning signed, HTTP-only auth cookies
- validating authenticated state
- enforcing authorization
- proxying auth flows to the private auth API
- talking to the auth server with service credentials
That architecture is intentional. Browser cookies should not be forwarded directly to
seamless-auth-api as if the auth server were your public application API.
@seamless-auth/express
Section titled “@seamless-auth/express”The Express package is the supported batteries-included server integration.
It provides:
createSeamlessAuthServer(...)requireAuth({ cookieSecret })requireRole(roleOrRoles)getSeamlessUser(...)createEnsureCookiesMiddleware(...)- scoped role helpers re-exported from
@seamless-auth/core createSeamlessConsoleProxy(...)and itsSeamlessConsoleProxyOptionstype
Typical shape
Section titled “Typical shape”import express from 'express'import cookieParser from 'cookie-parser'import createSeamlessAuthServer, { requireAuth, requireRole, type SeamlessAuthServerOptions,} from '@seamless-auth/express'
const app = express()app.use(express.json())app.use(cookieParser())
const authOptions: SeamlessAuthServerOptions = { authServerUrl: process.env.AUTH_SERVER_URL!, cookieSecret: process.env.COOKIE_SIGNING_KEY!, serviceSecret: process.env.API_SERVICE_TOKEN!, audience: process.env.AUTH_SERVER_URL!, jwksKid: process.env.JWKS_KID,}
app.use('/auth', createSeamlessAuthServer(authOptions))
app.get('/api/me', requireAuth({ cookieSecret: authOptions.cookieSecret }), (req, res) => { res.json({ user: req.user })})
app.get( '/admin/users', requireAuth({ cookieSecret: authOptions.cookieSecret }), requireRole('admin:read'), (_req, res) => { res.json({ ok: true }) },)Required options
Section titled “Required options”| Option | Purpose |
|---|---|
authServerUrl |
Base URL for the Seamless Auth instance |
cookieSecret |
Secret used to verify and sign adapter cookies |
serviceSecret |
Shared service secret for machine-to-machine calls to the auth instance |
audience |
Expected aud on the auth server’s tokens. The auth API sets it to its ISSUER, so this is authServerUrl, or the same value as authServerIssuer when that is set |
Optional values:
| Option | Default | Purpose |
|---|---|---|
authServerIssuer |
authServerUrl |
Expected iss on the auth server’s tokens and signed responses; see Auth server issuer |
jwksKid |
dev-main, with a startup warning |
kid header on the HS256 service tokens the adapter signs, not the auth API’s signing key ID; set it explicitly in production |
cookieDomain |
unset | Domain attribute for adapter cookies |
cookieSecure |
true |
Secure attribute; set false only for local HTTP |
cookieSameSite |
none if secure, else lax |
SameSite attribute for adapter cookies |
allowedOrigins |
unset | Origin allowlist for browsers without Sec-Fetch-Site |
resolveClientIp |
Express trust proxy hops |
End-user IP forwarded to the auth API |
messaging |
unset | Deliver auth email and SMS from the adapter |
allowedOrigins feeds the adapter’s cross-site request guard, which only runs when cookies are
SameSite=None and only for state-changing methods (not GET, HEAD, or OPTIONS). The guard
rejects Sec-Fetch-Site: cross-site with 403 { "error": "cross_site_request_blocked" }; when a
browser omits that header, the Origin must match an entry (case-insensitive), and with
allowedOrigins unset those requests are allowed.
Custom cookie names are also accepted (accessCookieName, registrationCookieName,
refreshCookieName, preAuthCookieName).
The Fastify seamlessAuth plugin takes the same options, authServerIssuer included.
Auth server issuer
Section titled “Auth server issuer”The adapter checks the iss of every token and signed response the auth server returns against
authServerIssuer, which defaults to authServerUrl. Requests and key set fetches always go to
authServerUrl; only the iss check reads authServerIssuer. Set it when your server reaches
the auth server at a different URL from the issuer it advertises (its ISSUER setting).
The usual case is an API run on the host against the seamless init --local Docker stack. The auth
server there signs as http://auth:5312, its compose service name, while the host-run API calls
http://localhost:5312, and without the option every sign-in fails with
Invalid signed response from Auth Server.
const authOptions: SeamlessAuthServerOptions = { authServerUrl: 'http://localhost:5312', authServerIssuer: 'http://auth:5312', audience: 'http://auth:5312', // ...}The auth API signs its ISSUER into aud as well, and audience is required with no default, so
with authServerIssuer set, set audience to the same value. The silent refresh on the /auth
routes checks the refreshed token against authServerIssuer too.
authServerIssuer is accepted by createSeamlessAuthServer, requireAuth, and getSeamlessUser
in @seamless-auth/express (0.19.1 or later), by the seamlessAuth plugin, requireAuth, and
getSeamlessUser in @seamless-auth/fastify (0.10.1 or later), and by the Next.js adapter
(Next.js). The Express and
Fastify starters read it from AUTH_SERVER_ISSUER (see
Environment Variables).
Managed vs self-hosted configuration
Section titled “Managed vs self-hosted configuration”The options are the same on both paths. Only the values differ, and where the service secret comes from.
| Option | Managed | Self-hosted |
|---|---|---|
authServerUrl |
Your Auth Server URL, copied from the portal | The auth API, for example http://localhost:5312 |
audience |
The same Auth Server URL | The same auth server URL, or authServerIssuer when set |
authServerIssuer |
Leave unset | http://auth:5312 when the API runs on the host against the Docker stack |
serviceSecret |
A service token generated in the portal (shown once) | The auth API’s API_SERVICE_TOKEN from your local stack |
On the managed path, generate the service token from your application’s Auth API Configuration
card and read it from a server-side environment variable. The portal’s connection snippet reads it
from SEAMLESS_SERVICE_TOKEN. See the Managed Quickstart. The
serviceSecret is never sent raw: the adapter uses it to sign short-lived service tokens for calls
to the auth instance.
Mounted Adapter Routes
Section titled “Mounted Adapter Routes”When mounted at /auth, the Express adapter exposes auth-compatible browser routes such as:
/auth/login/auth/oauth/providers/auth/oauth/:providerId/start/auth/oauth/:providerId/callback/auth/webAuthn/login/start/auth/webAuthn/login/finish/auth/webAuthn/register/start/auth/webAuthn/register/finish/auth/otp/*/auth/magic-link*/auth/step-up/*/auth/organizations/*/auth/users/me/auth/users/credentialsDELETE /auth/logoutDELETE /auth/logout/all/auth/admin/*/auth/internal/*/auth/system-config/*
The adapter route spelling is webAuthn; the raw auth API route group is /webauthn.
Auth Middleware
Section titled “Auth Middleware”requireAuth({ cookieSecret }) verifies the signed access cookie and attaches the decoded payload
to req.user.
app.get('/api/profile', requireAuth({ cookieSecret }), (req, res) => { res.json({ user: req.user })})This middleware verifies an already-issued access cookie. Session refresh is handled by the adapter’s cookie middleware.
With authServerUrl and audience it also accepts the auth API’s own access token in
Authorization: Bearer, verified against the auth API’s JWKS (issuer, audience, expiry and
typ: "access"). This is how a native client authenticates; see
Bearer Transport For Native Clients. A cookie wins when
both are present, and the two options must be given together.
const guard = requireAuth({ cookieSecret, authServerUrl: process.env.AUTH_SERVER_URL, audience: process.env.AUTH_SERVER_URL,})When the auth server signs under another issuer, also pass authServerIssuer and set audience
to it, as in Auth server issuer. It is only read when bearer tokens are
enabled. Fastify’s requireAuth takes the same options.
On the bearer path req.user.email and req.user.phone are not set, because the access token
does not carry them. getSeamlessUser(req, options) loads the profile for either credential.
requireRole(required) performs authorization only. It expects requireAuth to have populated
req.user.
app.post( '/settings', requireAuth({ cookieSecret }), requireRole(['admin:write', 'settings:write']), updateSettings,)Scoped role compatibility:
| Granted role | Satisfies |
|---|---|
admin |
admin, admin:read, admin:write |
admin:write |
admin:write, admin:read |
admin:read |
admin:read only |
Bearer Transport For Native Clients
Section titled “Bearer Transport For Native Clients”Browsers get the cookie contract: the adapter holds the auth API’s tokens in signed httpOnly
cookies and the page never sees them. A native app has no cookie jar, so the same routes serve a
second contract when a request carries the header x-seamless-auth-transport: bearer:
- The client presents the token a route needs in
Authorization: Bearer. Pre-auth routes (OTP, passkey login, magic link) take the ephemeral token/loginor/registration/registerreturned; signed-in routes take the access token. - Session-issuing responses come back whole,
tokenandrefreshTokenincluded, and no cookie is set. The adapter still verifies the auth API’s signature on the access token first. POST /auth/refreshrotates the session:Authorization: Bearer <refreshToken>in, a new pair out. The auth API treats a replayed refresh token as theft and revokes the chain (401 { "error": "refresh_token_reused" }), so a client refreshes once at a time.- Delivery mode, forwarded client IP and user agent, and the service token behave exactly as in cookie transport.
The header selects the transport rather than the presence of Authorization, because the first
request of a flow carries no token in either. Requests without the header are unchanged.
POST /auth/login -> { token: <ephemeral>, loginMethods, ... }POST /auth/otp/verify-login-email-otp -> { token: <access>, refreshToken, ... }GET /auth/users/me Authorization: Bearer <access>POST /auth/refresh Authorization: Bearer <refreshToken>@seamless-auth/react-native speaks this contract for you; the
React Native SDK page covers the client side. Your own routes accept
the same access token through requireAuth with authServerUrl and audience, above.
Messaging Delivery
Section titled “Messaging Delivery”The Express adapter can own email and SMS delivery for auth-message flows.
createSeamlessAuthServer({ authServerUrl, cookieSecret, serviceSecret, audience, messaging: { email: emailTransport, sms: smsTransport, handlers: { sendMagicLinkEmail: async (input) => { // Deliver input yourself, then report the outcome as a DeliveryResult. return { accepted: true, provider: 'my-mailer', channel: 'email' } }, }, },})When messaging is configured, the adapter requests external-delivery payloads from the auth API,
delivers OTPs or one-time links locally, and strips those sensitive payloads before responding to the
browser.
OAuth And Organizations
Section titled “OAuth And Organizations”The server adapter proxies OAuth and organization routes so your browser app can stay on the same cookie boundary.
OAuth provider configuration belongs on seamless-auth-api, not in the adapter. Configure
LOGIN_METHODS to include oauth, add oauth_providers, and store provider client secrets in env
vars referenced by clientSecretEnv.
Organization routes let authenticated users create organizations, switch active organization, and
manage organization members. Admin organization routes sit under /auth/admin/organizations/*.
Admin Hardening Routes
Section titled “Admin Hardening Routes”The adapter proxies admin hardening endpoints used by the dashboard:
DELETE /auth/admin/sessions/by-id/:idDELETE /auth/admin/sessions/:userId/revoke-allPOST /auth/admin/users/:userId/recovery/device-replacement
Device replacement recovery requires a fresh step-up session in the auth API. It revokes sessions, removes passkeys, disables TOTP credentials, and returns counts only.
@seamless-auth/core
Section titled “@seamless-auth/core”The core package is lower level and framework-agnostic.
It is designed for:
- custom adapters
- future framework integrations
- runtimes where you want full control over request and response handling
Key exports include:
ensureCookies(...)refreshAccessToken(...)verifyCookieJwt(...)createServiceToken(...)authFetch(...)getSeamlessUser(...)hasScopedRole(...)- login, registration, OTP, magic-link, OAuth, session, and organization handlers
Core functions return descriptive result objects. They do not set Express responses, read environment variables, or own framework-specific behavior.
Current Official Coverage
Section titled “Current Official Coverage”All three adapters are official packages of seamless-auth-server, published to npm and, like
@seamless-auth/core, still pre-1.0. The beta label you see in seamless init belongs to the
starter templates in seamless-templates, not to the adapter packages:
| Adapter | Package status | CLI starter template (status) |
|---|---|---|
@seamless-auth/express |
Official | express (stable) |
@seamless-auth/fastify |
Official | fastify (beta) |
@seamless-auth/nextjs |
Official | nextjs, a full-stack template (beta) |
Current versions and the ranges each adapter declares on @seamless-auth/core are in the
Compatibility Matrix.
The Python, Go, and Rust adapters are separate repositories (seamless-auth-python,
seamless-auth-go, seamless-auth-rust), released at 0.2.0 and also pre-1.0. They take their route
list from the adapter manifest the auth API serves from v0.18.0, and each runs the same conformance
suite in CI. Their api starters (gin, axum, fastapi) are on seamless-templates main and not
yet in a templates release the CLI pins.
Express is the most mature path. It is the reference adapter: the Fastify and Next.js adapters’
tests hold them to the Express adapter’s responses. It is also the only adapter released in lockstep
with @seamless-auth/core (their linked Changesets group), and its starter template is the only
stable backend template.
The most mature combination is:
@seamless-auth/react or @seamless-auth/react-native -> your frontend
@seamless-auth/express -> your backend integration layer
seamless-auth-api -> your auth engineThe Fastify adapter, @seamless-auth/fastify, mirrors the Express one as a Fastify plugin, bearer
transport included. A Next.js App Router application uses @seamless-auth/nextjs instead of a
separate backend: it serves /auth from a route handler and reads the session in server components
and proxy.ts (Next.js). Use @seamless-auth/core when none of the three fits
your Node.js runtime or you are building an adapter. For Python, Go, and Rust backends, use the
Python, Go, or Rust adapter.
Related Docs
Section titled “Related Docs”- Python: FastAPI And Django
- Go: net/http, chi, Echo, And Gin
- Rust: Axum
- How To Secure Routes
- How To Build Your Own Auth UI
- How To Add OAuth Login
- How To Use Organizations And Memberships
- How To Use TOTP And Step-Up
- React SDK
- React Native SDK
- Auth API Server
- Auth API Routes
- Cookie, Session, And Token Reference
- System Config Reference
- Environment Variables