Email and password sign-in with verification codes
Enable email and password sign-in with one-time verification codes using thelastapi auth settings, shared email delivery, or custom SMTP.
On this page 7 sections
You can configure email and password sign-in with verification codes by enabling email_password with one-time code (otp) verification in your project auth settings. thelastapi includes a sign-in service connected directly to your project database, supporting both development on localhost and live production traffic. You can deliver verification codes out of the box with the shared email sender or connect your own SMTP server for link-based confirmation.
When building an application, rolling your own user tables, hashing logic, verification tokens, and session cookies takes time away from your product. With thelastapi, adding sign-in brings along your database and handles password handling, email code generation, and session management with minimal code.
How email and password verification works
When you add the auth resource to a project, thelastapi provisions authentication services directly alongside your project's database. Sign-in data and user records are stored directly in your Postgres database, so you retain full control over user records without syncing data across external systems.
For email and password sign-in, the service exposes controls for how users create accounts and verify ownership:
- Sign-up control: You can enable standard registration or toggle
disable_sign_upto prevent public registrations. - Verification enforcement: Setting
require_email_verificationtotrueensures that unverified accounts cannot complete sign-in until their address is confirmed. - Verification methods: The platform supports one-time numeric codes (
otp) and verification links (link). - Post-verification behavior: With
auto_sign_in_after_verificationenabled, users immediately receive an authenticated session once they enter the valid code, without needing to type their password a second time.
If you are using the default shared email sender, verification is handled via one-time verification codes (otp). Link-style verification requires configuring your own SMTP server.
Configuring verification codes via the API
You can inspect and update your sign-in configuration using the CLI or plain HTTP requests against the /v1/projects/:id/auth/settings endpoint.
To view your current development settings from your terminal:
vibiz auth --devTo enable email and password sign-in with mandatory verification codes, send a PATCH request to update the sign-in settings for your environment.
curl -X PATCH "https://thelastapi.dev/v1/projects/prj_123/auth/settings?env=development" \
-H "Authorization: Bearer $VIBIZ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"app_name": "Acme App",
"email_password": {
"enabled": true,
"require_email_verification": true,
"email_verification_method": "otp",
"disable_sign_up": false,
"auto_sign_in_after_verification": true
}
}'The key fields inside the email_password configuration object control the registration cycle:
| Setting Field | Type | Description |
|---|---|---|
enabled | boolean | Enables email and password authentication for the environment. |
require_email_verification | boolean | Requires users to verify their email before accessing authenticated routes. |
email_verification_method | string | Set to "otp" for numeric verification codes or "link" for verification links. |
disable_sign_up | boolean | Prevents new users from creating an account when set to true. |
auto_sign_in_after_verification | boolean | Automatically creates an active session cookie once the code is confirmed. |
If you also want passwordless options for users, you can combine this flow with magic links or social logins. Learn more in our guides on magic link sign-in without building it yourself and how to add sign-in to a Next.js app.
Shared sender vs custom SMTP
Email delivery behavior depends on your sender configuration. thelastapi provides two options under email_sender:
- Shared sender (
type: "shared"): Uses the built-in email infrastructure. It requires zero configuration and works out of the box for delivering one-time verification codes (otp) and magic links. Because of reputation safeguards, link-style verification cannot be used with the shared sender. Attempting to setemail_verification_method: "link"while using the shared sender returns a400 invalid_requesterror. - Custom SMTP (
type: "smtp"): Lets you connect your own mail server by specifying your credentials. Custom SMTP supports bothotpcodes andlinkverification formats.
To switch to custom SMTP, provide your connection settings:
curl -X PATCH "https://thelastapi.dev/v1/projects/prj_123/auth/settings?env=development" \
-H "Authorization: Bearer $VIBIZ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"email_sender": {
"type": "smtp",
"host": "mail.example.com",
"port": 587,
"username": "smtp_user",
"password": "smtp_password",
"sender_email": "auth@example.com"
}
}'When checking your configuration via the API or CLI, credentials such as passwords and client secrets are never printed or returned in plaintext. Instead, the response includes boolean flags like has_password.
Handling sign-in in your application code
If you generate a project using the starter template (vibiz init my-app --template nextjs-saas), sign-in routes and UI components come pre-wired. The template handles the sign-up submission, the OTP verification form, and session validation.
When you boot your development environment with vibiz dev, the command populates .env.development.local with the necessary authentication variables:
vibiz devYour environment receives:
VIBIZ_AUTH_BASE_URL: The sign-in service URL for the current environment.VIBIZ_AUTH_COOKIE_SECRET: The secret key used to sign and verify user session cookies.VIBIZ_AUTH_JWKS_URLandVIBIZ_AUTH_PROJECT_ID: Used by services and edge middleware that verify tokens manually.
In server-side code, checking the current user session is handled with helper functions:
import { currentUser } from '@/lib/auth/server';
export default async function DashboardPage() {
const user = await currentUser();
if (!user) {
return <p>Please sign in to access your dashboard.</p>;
}
return (
<div>
<h1>Welcome back, {user.email}</h1>
</div>
);
}If you are running your app outside thelastapi hosting or on another server, install @vibiz/app and call await vibiz.loadEnv() at startup to import all necessary credentials directly into process.env. Read more in use one service.
Development vs production environments
Every project has two separate environments: development and production.
- Development: Created when you run
vibiz dev. It uses an isolated database branch with your schema but zero production rows. It runs its own sign-in instance and trustshttp://localhost:3000by default. AI calls and test auth events stay isolated from real users. - Production: Uses your live database and only accepts requests from trusted live domains.
allow_localhostis turned off by default in production.
This separation also affects permissions. AI coding agents using a Limited API key can safely read and edit development settings, including the app name, email verification toggles, and allowed domains. However, production sign-in settings are protected: attempting to update production settings with a Limited key results in a 403 forbidden error with details.reason: "owner_only". Production updates must be performed by a person with a Full-access key or via the console. Read more on permission levels in the keys and environments documentation.
Domain trust and email restrictions
Before your production app can process sign-ins on a custom domain, the sign-in service must trust that domain:
- thelastapi hosting: Domains bought through the platform or attached to internal hosting are trusted automatically with HTTPS enabled.
- External hosting: If you host your application elsewhere, connect the domain with
vibiz domains add app.example.com --elsewhere. Sign-in will trust it immediately when added with a Full-access key, or once the ownership TXT verification record is validated if added with a Limited key.
You can also restrict registrations by domain. If your application is internal or enterprise-focused, restrict sign-up using the CLI:
vibiz auth domains acme.com,partner.com --devThis prevents any user whose email address does not match the approved list from completing verification and signing up. To remove restrictions, run vibiz auth domains none --dev. For details on domain-level access control, see our guide on how to restrict sign-up to your company's email domain.
If you need a new domain for your application, you can search and buy one directly from the CLI with vibiz domains search acme and vibiz domains buy acme.app, with DNS records and sign-in trust configured automatically. See the domains documentation for complete instructions.
To deploy a complete application with database, authentication, and hosting ready in minutes, review our guide on how to deploy a Next.js app with a database and sign-in in one command. For API route specifications, consult the sign-in documentation.
Frequently asked questions
Can I use verification links instead of one-time numeric codes?
Verification links are supported only when you configure your own custom SMTP server. If you use the shared email sender, you must use one-time verification codes (`otp`).
How do I test email verification codes during local development?
When running locally with `vibiz dev`, authentication uses a dedicated development environment that trusts `http://localhost:3000`. You can test registration and enter verification codes without touching production user tables.
What happens if an unverified user tries to log in?
When `require_email_verification` is set to `true`, the sign-in service prevents unverified users from receiving an authenticated session until they submit the valid verification code sent to their email.
Can an AI agent update our production sign-in settings?
No, Limited API keys used by agents receive a `403 owner_only` error when attempting to update production sign-in settings. Production authentication changes require a Full-access key or an owner in the console.