Email & password

The moment you run agentry auth enable (with a database bound), your app gets full email-and-password accounts — sign-up, sign-in, sessions — with no extra setup. Add an SMTP service and you also get password reset and optional email verification.

If you haven't yet, read Authentication first for how the login layer works.

What you get immediately

After agentry auth enable:

• A sign-in page and a sign-up page, rendered for you.
• Accounts stored in your bound database (Postgres, MySQL, or MongoDB).
• Passwords stored only as bcrypt hashes — never in plain text.
• A signed, HttpOnly session cookie that keeps users logged in for 30 days.
• A sign-out action and a small /auth/me endpoint your app can call to read the current user.

Users hit your app, get the sign-in screen, create an account, and land back in your app — all without you building any of it.

The built-in pages

Page	What it does
/auth/login	Sign in with email + password
/auth/signup	Create a new account
/auth/logout	Sign out (clears the session)
/auth/forgot	Request a password-reset email (needs SMTP)
/auth/reset	Set a new password from a reset link (needs SMTP)

You don't have to link to these — unauthenticated visitors are sent to the sign-in page automatically. To add a sign-out control, POST to /auth/logout (it's a POST, not a GET — use a small form or button, not a plain link).

Password rules

New passwords must be:

• at least 8 characters,
• not one of the common/breached passwords (password, qwerty123, …),
• not a single repeated character (aaaaaaaa).

That's enforced on sign-up and on password reset.

Password reset (requires email)

Password reset only works once an SMTP service is bound, because it needs to send mail. To turn it on:

agentry service bind smtp
agentry auth enable        # re-run to pick up the new capability

Binding SMTP asks for your mail relay's details — host, port (587 with STARTTLS by default, or 465 for implicit TLS), username and password if your relay needs them, and the From address mail is sent as (e.g. Acme <noreply@acme.com>). Use any provider you like — a transactional service like Postmark, SES, or Resend, or your own server.

Once it's bound, the sign-in page shows a Forgot password? link and the flow works like this:

1. The user enters their email on /auth/forgot.
2. They always see the same confirmation — "if an account exists, we've sent a link" — so the page can't be used to discover who has an account.
3. If the email is on file, a reset link is sent. The link is valid for one hour and can be used once.
4. They set a new password and sign in with it.

Optional: require email verification

If you want new users to confirm their email before they can sign in, enable verification (this also needs SMTP). New accounts then receive a verification link, valid for 24 hours, and can't sign in until they click it. Ask your agent to set AGENTRY_AUTH_REQUIRE_VERIFICATION=true in the sandbox env, or set it in the deployment's Env tab.

Built-in security

You don't have to configure any of this — it's on by default:

• Rate limiting. Sign-in, sign-up, and forgot-password are capped at 10 attempts per minute per IP. Past that, the visitor gets a "try again in a minute" response.
• Account lockout. The first four wrong passwords on an account are free (typos happen). The fifth locks the account for a minute, and each further wrong attempt doubles the wait, up to 30 minutes. A successful sign-in or a password reset clears it.
• CSRF protection. Sign-in and other form posts are checked against the page's origin and a per-form token, so another site can't submit them on a user's behalf.
• Sealed sessions. The session cookie is cryptographically signed, marked HttpOnly (JavaScript can't read it), and scoped to the exact domain — so your preview URL, your *.agentry.live URL, and your custom domain each keep separate sessions.

Testing it in development

Auth is wired into the sandbox the moment it's enabled, so you can try the whole flow before you ship:

1. Open the sandbox and Share it (see Quick start).
2. Visit the preview URL — you'll get the sign-in screen.
3. Create an account, sign in, and click around as a logged-in user.

If something's off, ask the agent to set AGENTRY_AUTH_DEBUG=1 in the sandbox; the login layer then logs its configuration (with secrets redacted) at startup so you can see what it picked up.

Next

• Social login — add Google, GitHub, Microsoft, Apple, or OIDC alongside email/password.
• Authentication overview — how your app reads the signed-in user.