Skip to content
agent-cms
Guides / Sign-in of its own

Guides / sign-in

Sign-in of its own

People, passwords, passkeys, two-step codes, single sign-on and invitations, for apps without a login.

Updated Nov 22, 2026by docs seedVersion 1
On this page

Most apps already have a login and pass it in with resolveUser. When yours does not (or for the standalone server), the CMS can sign people in itself.

ts
import { createAuth } from "@mainsoft/agent-cms/auth";
import { createCmsHandler } from "@mainsoft/agent-cms/http";

const auth = createAuth({
  cms,
  origin: "https://cms.example.com", // passkeys and mail links use it
  appName: "Example CMS",
  sendMail: async ({ to, subject, text }) => { /* Resend, SES, SMTP… */ },
  oidc: { issuer: "https://accounts.google.com", clientId, clientSecret, label: "Google", allowedDomains: ["example.com"] },
});
export const handler = createCmsHandler({ cms, auth });

Nothing new goes into the database schema: people, sessions, passkeys and one-time links live in cms_records.

The first admin#

While nobody has an account, the server prints a setup code where it logs (valid for 15 minutes; a new one comes with the next request after that):

text
[agent-cms] No one can sign in yet. Open https://cms.example.com/admin/setup and enter the setup code K7M2-9XQ4 (valid for 15 minutes).

POST /auth/setup with the code makes the first admin. After that, setup is closed.

Ways to sign in#

PasswordAt least 12 characters; common and guessable ones are refused (the 10,000 most common, the email name, runs like abcdefgh…). Hashed with scrypt (N=2^17, r=8, p=1); weaker hashes are replaced at the next sign-in. Turn passwords off with passwords: false.
PasskeyWebAuthn without a library: ES256, EdDSA, RS256; no email typed first. A passkey counts as two factors.
Two-step codeAny authenticator app (TOTP, RFC 6238), a QR code on setup, ten recovery codes that work once. "Trust this device" skips the code for 30 days.
Single sign-onOpenID Connect with PKCE: Google, Microsoft Entra, Okta, Keycloak, Auth0… allowedDomains limits who may sign in (and lets them in without an invitation, unless autoCreate: false).

Sessions#

  • An HttpOnly, SameSite=Lax cookie; on HTTPS it is __Host-cms_session and Secure. Only a hash of it is stored.
  • 30 days from the last use, at most 90 days.
  • Ten wrong passwords for one email in 15 minutes pause password sign-in for that email (passkeys and SSO still work); fifty tries from one address in 15 minutes pause that address.
  • Changing the password ends your other sessions; a reset ends all of them; switching someone off or taking admin away ends theirs at once.
  • Making or rotating API keys, turning two-step off, removing a passkey, and switching people off or making them admin need a confirmation in the last 10 minutes (POST /auth/reauth, or a passkey).
  • Requests that change something must come from the CMS's own page (login CSRF is refused).

People#

Admins invite by email (POST /users/invite, links valid for 7 days, with a role and optionally as admin). Without sendMail the answer has the links to copy. The policy requireMfa makes everyone set up a passkey or two-step codes before anything else. At least one admin always stays.

Every step is in the audit log (auth.* actions).

From code#

ts
await auth.createUser({ email: "park@example.com", name: "Park", password, isAdmin: true });
const link = await auth.resetLink("park@example.com");

The routes are listed under "sign-in", "account" and "people" in /openapi.json.