Add sign-in to an app hosted anywhere
Add authentication to an app hosted anywhere by creating an auth resource, registering your domain with --elsewhere, and loading env vars via one key.
On this page 8 sections
You can add authentication to an app hosted anywhere by provisioning an auth resource with thelastapi, registering your external domain with the --elsewhere flag, and loading your environment variables using VIBIZ_APP_KEY. Your backend receives managed user management, session handling, and credential verification backed by a dedicated Postgres database. You do not need to move your application or use our hosting to run our sign-in service.
This guide walks through configuring sign-in for an external server, establishing domain trust, setting up authentication methods, and reading environment secrets in your codebase.
How does sign-in work when hosting elsewhere?
Every service on thelastapi can run as an independent building block, as explained in the Use one service documentation. When you create an authentication service, the platform provisions user tables and session storage inside a dedicated Postgres database. Because sign-in stores user records in your database, adding the auth resource automatically attaches database to the project. If you need direct database queries alongside sign-in, read our guide on how to use a managed Postgres database from an app hosted anywhere.
Your application talks to the sign-in service using standard HTTP endpoints and session cookies. To secure this setup across different hosting environments, the sign-in service checks incoming origins against trusted domains registered to your project. The live environment requires a verified domain before accepting sign-in requests, while the local development copy automatically trusts http://localhost:3000.
To connect your external host to your project, you only need to store a single secret on your host: VIBIZ_APP_KEY. At server startup, your code uses that key to pull down its authentication configuration and connection strings into process.env.
Step 1: Create a project with authentication
To get started, initialize a project containing the auth resource:
vibiz init my-auth-app --resources authBecause adding auth brings database, this command creates both the authentication service and your project database.
Next, set up your local development environment:
vibiz devRunning vibiz dev provisions an isolated development copy with its own user store and writes the configuration values into .env.development.local. In this development copy, http://localhost:3000 is trusted by default so you can test user registration and log in on your local machine.
Step 2: Register and trust your production domain
Before your external server can process live sign-ins, the sign-in service must know which origin to trust. If an unknown domain tries to authenticate against your project, the request is rejected.
Register your external domain using the --elsewhere flag:
vibiz domains add app.example.com --elsewhereHow this domain becomes trusted depends on the type of API key you use:
- Full-access key (Owner): If an account owner runs the command, the domain is trusted immediately.
- Limited key (Agent or CI): If a Limited key adds the domain, the CLI provides a DNS verification TXT record (
trust_record) named_vibiz.app.example.com. Once you add that TXT record to your DNS host, run:
vibiz domains verify app.example.comAlternatively, an account owner can confirm the domain manually in the console. Once verified, the sign-in service permits cookie exchanges and redirects for app.example.com and its www. subdomain. More details on domain settings can be found in the Domains reference.
Step 3: Configure authentication methods
thelastapi supports email and password, magic links, and social sign-in via Google and GitHub. You can configure sign-in settings using the CLI or via HTTP requests.
Social sign-in
Turn on Google authentication for your development environment:
vibiz auth providers add google --devGoogle sign-in supports shared keys, meaning you can test authentication without creating your own OAuth app. You can also enable GitHub authentication:
vibiz auth providers add github --devMagic links and email restrictions
You can configure sign-in rules such as allowed email domains and magic link lifetimes. For example, to restrict sign-ups to company email addresses and adjust magic link validity:
# Allow only specific corporate email domains
vibiz auth domains acme.com,partner.com --dev
# Clear domain restrictions so anyone can sign up
vibiz auth domains none --devYou can also send a PATCH request directly to 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 '{
"magic_link": {
"enabled": true,
"expires_in_minutes": 30
},
"allowed_email_domains": ["acme.com"]
}'The table below outlines current configuration fields and their limits from the Sign-in documentation:
| Setting | Field | Limits / Values |
|---|---|---|
| App name | app_name | 1–256 characters |
| Magic link lifetime | magic_link.expires_in_minutes | 5–1440 minutes |
| Allowed domains | allowed_email_domains | Up to 50 domains (empty = open sign-up) |
| Email verification | email_password.email_verification_method | otp (shared sender) or link (custom SMTP) |
| Social providers | providers | google, github |
If you are using password workflows, see our deep-dive on email and password sign-in with verification codes. If you prefer passwordless authentication, check out magic link sign-in without building it yourself.
Step 4: Inject the environment into your external host
When hosting on third-party servers, virtual machines, or container services, you do not need to paste multiple database URLs and signing secrets into your dashboard. You only add VIBIZ_APP_KEY.
Loading environment variables in Node.js
Install the @vibiz/app package into your project:
npm install --save-exact @vibiz/app@0.3.15At the very top of your server entrypoint, load the environment:
import { vibiz } from '@vibiz/app';
// Injects VIBIZ_AUTH_*, DATABASE_URL, and other secrets into process.env
await vibiz.loadEnv();When vibiz.loadEnv() runs, it fetches your project's runtime variables over HTTPS using VIBIZ_APP_KEY and populates process.env. The authentication variables loaded include:
VIBIZ_AUTH_BASE_URL: The URL of the authentication service for the current environment.VIBIZ_AUTH_COOKIE_SECRET: The secret key used to sign and verify session cookies.VIBIZ_AUTH_JWKS_URL: The JSON Web Key Set URL for independent token verification.VIBIZ_AUTH_PROJECT_ID: The unique identifier for your project.DATABASE_URL: The Postgres connection string where user tables reside.
Loading environment variables in other runtimes
If your server runs another language or you prefer pulling variables prior to starting the process, use one of the following methods:
# Evaluate variables directly in a shell script
eval "$(curl -fsS -H "Authorization: Bearer $VIBIZ_APP_KEY" \
https://thelastapi.dev/v1/app/env?format=shell)" && exec node server.js
# Pull environment variables into a file during CI/CD build
npx @vibiz/cli env pull --format dotenv -o .env.productionIf you are building with Next.js on an external platform, our starter template wires sign-in handling out of the box (currentUser() in lib/auth/server.ts). Learn more in how to add sign-in to a Next.js app.
Key permissions and agent automation
Understanding key permissions ensures your production authentication settings stay secure while allowing automated tools to configure development environments. Read the Keys and environments guide for a complete reference on access models.
| Capability | Limited Key (Agents, CI) | Full-Access Key (Owner) |
|---|---|---|
| Read development env values | Yes | Yes |
| Modify development auth settings | Yes | Yes |
| Add external domains | Yes (requires TXT record check) | Yes (immediately trusted) |
| View production secret values | No (names only) | Yes |
| Modify production auth settings | No (403 owner_only) | Yes |
| Rotate production app keys | No | Yes |
When an AI agent or Limited key attempts to update production sign-in settings or read production secrets, the API returns 403 forbidden with details.reason: "owner_only" and provides a details.grant_url. An owner can visit that URL to approve the specific action.
Next steps
To get started, run vibiz init my-app --resources auth in your terminal and test the sign-in flow locally with vibiz dev. When you are ready for production, register your live domain with vibiz domains add <your-domain> --elsewhere, place VIBIZ_APP_KEY in your hosting provider's dashboard, and let await vibiz.loadEnv() manage your credentials. Create your account at thelastapi.dev/start to get started.
Frequently asked questions
Do I have to migrate my database or hosting to use sign-in?
No, your application can run on any server, container, or serverless platform. Adding the `auth` resource provisions a dedicated Postgres database alongside the sign-in service, which you connect to using `VIBIZ_APP_KEY` and your domain.
What email verification methods are supported?
The shared email sender supports one-time verification codes (`otp`). Link-based verification requires configuring your own SMTP sender credentials under the project's email settings.
Are multi-factor authentication (MFA) and user banning available today?
No, multi-factor authentication, custom email templates, configurable session lifetimes, and banning users are not available yet.
What happens if an external domain is not added to the project?
The sign-in service refuses requests and cookie exchanges from unregistered origins. You must add the domain using `vibiz domains add <domain> --elsewhere` and complete verification before production sign-ins will work.