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

**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_up` to prevent public registrations.
- **Verification enforcement**: Setting `require_email_verification` to `true` ensures 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_verification` enabled, 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:

```bash
vibiz auth --dev
```

To enable email and password sign-in with mandatory verification codes, send a `PATCH` request to update the sign-in settings for your environment.

```bash
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](https://thelastapi.dev/blog/magic-link-sign-in) and [how to add sign-in to a Next.js app](https://thelastapi.dev/blog/add-sign-in-nextjs-app).

## Shared sender vs custom SMTP

Email delivery behavior depends on your sender configuration. thelastapi provides two options under `email_sender`:

1. **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 set `email_verification_method: "link"` while using the shared sender returns a `400 invalid_request` error.
2. **Custom SMTP (`type: "smtp"`)**: Lets you connect your own mail server by specifying your credentials. Custom SMTP supports both `otp` codes and `link` verification formats.

To switch to custom SMTP, provide your connection settings:

```bash
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:

```bash
vibiz dev
```

Your 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_URL` and `VIBIZ_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:

```ts
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](https://thelastapi.dev/docs/use-one).

## 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 trusts `http://localhost:3000` by 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_localhost` is 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](https://thelastapi.dev/docs/keys).

## 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:

1. **thelastapi hosting**: Domains bought through the platform or attached to internal hosting are trusted automatically with HTTPS enabled.
2. **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:

```bash
vibiz auth domains acme.com,partner.com --dev
```

This 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](https://thelastapi.dev/blog/restrict-sign-up-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](https://thelastapi.dev/docs/domains) 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](https://thelastapi.dev/blog/deploy-nextjs-app-database-sign-in). For API route specifications, consult the [sign-in documentation](https://thelastapi.dev/docs/sign-in).

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

---

Published 2026-11-15 · https://thelastapi.dev/blog/email-password-sign-in-verification
