What you just built
A real app authenticating against a hosted Seamless Auth instance: passwordless sign-in, a server-side security boundary, a portal for plans and tokens, and an admin console for users and roles. No auth infrastructure to operate.
This guide takes you from signing up on the Seamless Auth portal to a real app where a user can sign in, using a hosted auth instance that Seamless runs for you. You do not run a database, signing keys, or an auth server on this path.
If you would rather run the whole stack yourself, follow the Self-Hosted Quickstart instead. Not sure which path fits? See Managed or Self-Hosted.
npm is used below)Open the Seamless Auth portal at https://dashboard.seamlessauth.com and sign up.
The portal is itself passwordless and built on Seamless Auth, so there is no password to choose:
You now have a portal account. The portal is where you create applications, manage plans and billing, generate service tokens, and review logs and auth events for each application. End users and roles live in the admin console bundled with each instance, which the portal links to.
An application is one hosted auth instance. From the dashboard, choose Create your first application (or New Application) and fill in the form.
Basic fields:
https://...)Advanced fields are optional and have safe defaults. They include notification email(s), application roles and default role, a development-mode toggle, AWS region, access and refresh token TTLs, and rate-limit thresholds.
| Plan | Price | Notes |
|---|---|---|
| Trial | Free | 14 days on MVP or Business, card required |
| MVP | $49 / mo | |
| Business | $149 / mo | Recommended for most new products |
| Enterprise | Contact sales | Not self-serve, email support@fellscode.com |
For a paid plan or a trial, the portal sends you through Stripe checkout before provisioning.
After you submit, Seamless provisions the instance. This takes a few minutes (the portal estimates about five). When it finishes, the application has its own Auth Server URL. This URL is what your backend adapter points at (your frontend points at your backend).
Copy it from the application’s Credentials page, in the Auth API Configuration card, rather than building it by hand. The host depends on the plan:
| Plan | Auth Server URL |
|---|---|
| Trial | https://<infra-id>.trials.seamlessauth.com |
| Paid plans | https://<infra-id>.seamlessauth.com |
<infra-id> is an identifier the portal assigns when it provisions the instance, not your
application name. Upgrading a trial moves the instance to the paid host, so copy the URL again after
an upgrade.
Your backend authenticates to the hosted auth instance with a service token. Generate it from the application’s Auth API Configuration card:
The full token is shown once. Copy it immediately and store it as a server-side secret. The portal keeps only a masked copy (the last few characters) for reference, so it cannot show you the full value again.
The service token is a long, URL-safe secret. Your backend reads it from an environment variable
(shown as SEAMLESS_SERVICE_TOKEN below); the frontend never sees it.
Your backend runs the Seamless Auth adapter. It is the only piece that talks to the hosted instance: it holds the service token, sets the session cookies in the browser, and calls the Auth Server URL over bearer tokens. The browser never talks to the Auth Server URL directly.
Install the Express adapter and CORS middleware in your backend project:
npm install @seamless-auth/express corsMount the adapter at /auth. Point authServerUrl and audience at your Auth Server URL, read
from AUTH_SERVER_URL:
import cors from 'cors';import express from 'express';import createSeamlessAuthServer from '@seamless-auth/express';
const app = express();
// The browser SDK sends cookies, so the frontend origin must be allowed with credentials.app.use(cors({ origin: process.env.FRONTEND_ORIGIN, credentials: true }));
app.use( '/auth', createSeamlessAuthServer({ authServerUrl: process.env.AUTH_SERVER_URL!, audience: process.env.AUTH_SERVER_URL!, cookieSecret: process.env.COOKIE_SIGNING_KEY!, serviceSecret: process.env.SEAMLESS_SERVICE_TOKEN!, // from the portal, shown once jwksKid: process.env.JWKS_KID!, }),);
app.listen(3000);Set these environment variables on your backend:
| Variable | Value |
|---|---|
AUTH_SERVER_URL |
Your Auth Server URL, copied from Credentials → Auth API Configuration |
SEAMLESS_SERVICE_TOKEN |
The service token generated in Step 3 |
COOKIE_SIGNING_KEY |
A random secret of at least 32 characters, for example from openssl rand -base64 48 |
JWKS_KID |
kid header on the service tokens your adapter signs; the auth API does not check it, and seamless init writes your instance’s active key id from /.well-known/jwks.json |
FRONTEND_ORIGIN |
Your frontend’s origin, for example http://localhost:5173 |
The service token is never sent raw. The adapter uses it to sign short-lived service tokens for
machine-to-machine calls to your hosted instance. To protect routes, add requireAuth and
requireRole from the same package. See the Server SDKs reference for the full
option list and middleware.
Install the React SDK in your frontend project:
npm install @seamless-auth/reactWrap your app in AuthProvider, using your backend’s origin as apiHost, then read session state
with useAuth(). The SDK calls the adapter you mounted at /auth on that origin.
import { AuthProvider, useAuth } from '@seamless-auth/react';
const API_URL = 'http://localhost:3000';
export function App() { return ( <AuthProvider apiHost={API_URL}> <AppRoutes /> </AuthProvider> );}
function AppRoutes() { const { isAuthenticated, user } = useAuth();
return isAuthenticated ? <p>Signed in as {user?.email}</p> : <LoginPage />;}AuthProvider needs only apiHost; its other props are optional. There is no frontend token or
client id: the browser SDK carries no secret and relies on the cookies your backend sets. For
built-in sign-in screens, mount AuthRoutes from @seamless-auth/react/routes; for custom UI, use
the headless client. See the React SDK reference for the full API.
Run your frontend and backend, then sign in:
useAuth() reports the user as authenticated.Back in the portal, the application’s Logs page records the sign-in on its Auth events tab, and the Users count on the application Dashboard includes the new account.
To manage that user, choose Open admin console on the application Dashboard. It opens the
admin console bundled with your instance (at /console on your instance URL). Its Users screen
lists end users (open one to edit its roles), its Events screen shows the auth event stream, and
its System screen defines the available and default roles. See
Explore the Admin Dashboard for a tour.
What you just built
A real app authenticating against a hosted Seamless Auth instance: passwordless sign-in, a server-side security boundary, a portal for plans and tokens, and an admin console for users and roles. No auth infrastructure to operate.
| You need to | Go to |
|---|---|
| Copy your Auth Server URL | Credentials → Auth API Configuration |
| Generate or rotate the token | Credentials → Auth API Configuration → Service Token |
| See sign-ins and auth events | Logs → Auth events tab |
| Manage end users and roles | Dashboard → Open admin console → Users |
| Change or upgrade your plan | Billing → Change plan |
| Re-run the connection steps | Dashboard → Get connected (Connection guide once completed) |