Magic link sign-in without building it yourself
Implement magic link authentication with a managed sign-in service, configurable link lifetimes, and automated session cookies without building auth code.
On this page 9 sections
You can add passwordless magic link authentication to your application using a managed sign-in service that handles token generation, email dispatch, and session cookies. Instead of creating database tables, hashing tokens, and maintaining custom email logic, you enable magic links with an API call or CLI command. Your app triggers the sign-in email, your user clicks the link, and the platform verifies the token and issues a secure session cookie.
Building authentication from scratch often leads to security risks, expired token bugs, and maintenance overhead. This guide shows how to configure magic link sign-in, wire it into a web application, and manage environments safely.
How magic link authentication works
Passwordless magic links replace passwords with temporary, cryptographically signed tokens delivered by email. Here is what happens under the hood when a visitor signs in:
- Request: The user enters their email address into your sign-in form.
- Token generation: Your app asks the sign-in service to issue an authentication token tied to that email.
- Dispatch: An email containing a unique sign-in link is sent to the user's inbox.
- Verification: The user clicks the link, returning to your application's callback route.
- Session creation: The sign-in service verifies the token, marks the email as valid, creates a user record in the project's Postgres database if one does not exist, and returns a signed session cookie.
The sign-in service stores your application's users directly in your project database. Adding the auth resource to a project automatically provisions database, ensuring user records, identities, and session data live in your own database schema rather than an isolated third-party silo.
Creating a project and enabling magic links
You can enable authentication when you initialize a project or add it to an existing project at any time.
To start a new project with authentication:
vibiz init "Acme App" --resources authIf you already have a project without authentication, add the resource using the CLI:
vibiz add authBecause auth relies on a database, adding auth brings the database resource automatically if it was not already attached.
Configuring magic link settings
Magic link behavior is configured per environment. You can set the lifetime of the link, customize the application name shown in emails, and restrict which email domains can authenticate.
To enable magic links in your development environment, call the settings API:
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",
"magic_link": {
"enabled": true,
"expires_in_minutes": 30
}
}'The table below outlines the core settings available for sign-in and magic links:
| Setting | Field | Description | Range / Options |
|---|---|---|---|
| App Name | app_name | The name displayed in verification and sign-in emails | 1–256 characters |
| Magic Link Enabled | magic_link.enabled | Turns passwordless magic link sign-in on or off | true or false |
| Link Lifetime | magic_link.expires_in_minutes | How long the link remains valid before expiring | 5–1440 minutes |
| Allowed Domains | allowed_email_domains | Restricts sign-ups to specific corporate domains | Up to 50 domains (empty allows all) |
| Localhost Support | allow_localhost | Allows callback requests on http://localhost:3000 | On by default in development |
If you need password-based login alongside magic links, refer to our guide on email and password sign-in with verification codes. You can also provide social sign-in options; see how to add Google sign-in to your app without your own OAuth app for a faster sign-in flow.
Email senders and delivery
Magic links require email delivery. The sign-in system supports two types of email senders:
- Shared sender: The default sender provided with the service (
{ "type": "shared" }). Note that link-style email verification requires your own SMTP configuration, while the shared sender handles one-time codes (otp). - Custom SMTP sender: Connect your own mail server to send emails directly from your domain using your own credentials:
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": "smtp.example.com",
"port": 587,
"username": "smtp_user",
"password": "smtp_password",
"sender_email": "auth@example.com"
}
}'Setting a custom SMTP sender ensures links arrive from your branded domain rather than a generic shared sender.
Integrating magic links into a web application
When you initialize an application with the SaaS template (vibiz init --template nextjs-saas), authentication routes and session helpers are preconfigured. For custom Next.js integrations, check how to add sign-in to a Next.js app.
Running vibiz dev writes your development environment credentials to .env.development.local:
vibiz devYour environment receives the following variables:
| Variable | Description |
|---|---|
VIBIZ_AUTH_BASE_URL | The sign-in service for this environment |
VIBIZ_AUTH_COOKIE_SECRET | Signs the session cookie |
VIBIZ_AUTH_JWKS_URL | For code that verifies tokens itself |
VIBIZ_AUTH_PROJECT_ID | The project identifier for token verification |
In your application code, load environment variables using @vibiz/app at server boot:
import { vibiz } from '@vibiz/app';
await vibiz.loadEnv();In the nextjs-saas template, /api/auth/* serves the sign-in flows, including magic link submission and verification callbacks. The incoming link verifies the authentication token and sets an encrypted session cookie signed by VIBIZ_AUTH_COOKIE_SECRET.
To read the current session in server-rendered components or API routes:
import { currentUser } from '@/lib/auth/server';
export default async function DashboardPage() {
const user = await currentUser();
if (!user) {
return <p>Please sign in to view your account.</p>;
}
return <h1>Welcome back, {user.email}</h1>;
}The currentUser() helper inspects the session cookie, decodes the authenticated identity, and queries the user record directly from your project's database.
Restricting sign-ups to specific email domains
If you are building an internal company tool or a private B2B portal, you can restrict sign-ups to authorized corporate domains:
vibiz auth domains acme.com,partner.com --devTo remove the restriction and allow public sign-ups again:
vibiz auth domains none --devYou can specify up to 50 domains. Anyone attempting to request a magic link with an email outside the list will be rejected automatically.
Managing environments and domains
Every project contains two distinct environments:
- development: Uses an isolated database branch with the same schema but no live rows. Sign-in trusts
http://localhost:3000automatically. - production: Uses the live database. Sign-in trusts only the approved project domains.
If you run your frontend outside the built-in hosting platform, you must explicitly connect your domain so sign-in trusts callback requests. See our guide on how to use one service independently.
Register your external domain:
vibiz domains add app.example.com --elsewhereIf you use a Limited key, sign-in will trust the domain once you add the verification TXT record (trust_record) to your DNS and run:
vibiz domains verify app.example.comAlternatively, the account owner can confirm the domain in the console. If you bought your domain directly through the platform, no DNS records are required; the domain is verified and trusted instantly. You can inspect domain details under Domains.
API key permissions and AI agents
AI agents like Claude Code, Codex, or Cursor can help configure your sign-in flows. Understanding key privileges ensures agents do not modify live systems unintentionally:
- Limited keys (
vz_sk_...,access: agent): Can configure the development environment, update development magic link lifetimes, adjust allowed domains, and deploy changes. When a Limited key attempts to update production auth settings, the API returns a403 forbiddenerror withdetails.reason: "owner_only". - Full-access keys (
vz_sk_...,access: owner): Held by human owners and CI environments. Required to update production authentication settings or rotate production app keys.
To give a Limited key permission to update production sign-in settings without granting full owner access, assign the auth.production:write permission:
vibiz keys access key_123 allow auth.production:writeFor more details on key scoping and environment boundaries, see Keys and environments.
What to do next
Magic links remove password friction while keeping sign-in flows tied to your own database. To review all authentication parameters and endpoints, visit the Sign-in documentation. To enable social logins alongside magic links, follow our guide to add Google sign-in to your app without your own OAuth app.
Frequently asked questions
How long can a magic link remain valid?
You can configure the magic link expiration time between 5 minutes and 1440 minutes (24 hours) using the `magic_link.expires_in_minutes` setting.
Can I restrict magic link authentication to internal company employees?
Yes. You can define up to 50 allowed email domains using `vibiz auth domains example.com` or by updating the `allowed_email_domains` setting in your project configuration.
Do magic links work on localhost during local development?
Yes. The development environment trusts `http://localhost:3000` by default, allowing you to test magic link callbacks locally before pushing to production.
Can an AI agent configure magic link authentication in production?
By default, Limited keys used by AI agents can only modify development sign-in settings. Production configuration requires a full-access key or the specific `auth.production:write` permission granted by the project owner.