Skip to content

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-auth on PyPI, for FastAPI and Django (Python)
  • Go: github.com/fells-code/seamless-auth-go, for net/http, chi, Echo, and Gin (Go)
  • Rust: seamless-auth on crates.io, for Axum (Rust)

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.


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.


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 its SeamlessConsoleProxyOptions type
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 })
},
)
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.

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).

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.


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/credentials
  • DELETE /auth/logout
  • DELETE /auth/logout/all
  • /auth/admin/*
  • /auth/internal/*
  • /auth/system-config/*

The adapter route spelling is webAuthn; the raw auth API route group is /webauthn.


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

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 /login or /registration/register returned; signed-in routes take the access token.
  • Session-issuing responses come back whole, token and refreshToken included, and no cookie is set. The adapter still verifies the auth API’s signature on the access token first.
  • POST /auth/refresh rotates 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.


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.


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/*.


The adapter proxies admin hardening endpoints used by the dashboard:

  • DELETE /auth/admin/sessions/by-id/:id
  • DELETE /auth/admin/sessions/:userId/revoke-all
  • POST /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.


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.


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 engine

The 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.