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

**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](https://thelastapi.dev/docs/use-one) 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](https://thelastapi.dev/blog/postgres-from-any-host).

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:

```bash
vibiz init my-auth-app --resources auth
```

Because adding `auth` brings `database`, this command creates both the authentication service and your project database.

Next, set up your local development environment:

```bash
vibiz dev
```

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

```bash
vibiz domains add app.example.com --elsewhere
```

How this domain becomes trusted depends on the type of API key you use:

1. **Full-access key (Owner)**: If an account owner runs the command, the domain is trusted immediately.
2. **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:

```bash
vibiz domains verify app.example.com
```

Alternatively, 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](https://thelastapi.dev/docs/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:

```bash
vibiz auth providers add google --dev
```

Google sign-in supports shared keys, meaning you can test authentication without creating your own OAuth app. You can also enable GitHub authentication:

```bash
vibiz auth providers add github --dev
```

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

```bash
# 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 --dev
```

You can also send a `PATCH` request directly to the settings API:

```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 '{
    "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](https://thelastapi.dev/docs/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](https://thelastapi.dev/blog/email-password-sign-in-verification). If you prefer passwordless authentication, check out [magic link sign-in without building it yourself](https://thelastapi.dev/blog/magic-link-sign-in).

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

```bash
npm install --save-exact @vibiz/app@0.3.15
```

At the very top of your server entrypoint, load the environment:

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

```bash
# 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.production
```

If 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](https://thelastapi.dev/blog/add-sign-in-nextjs-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](https://thelastapi.dev/docs/keys) 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](https://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.

---

Published 2026-11-15 · https://thelastapi.dev/blog/sign-in-app-hosted-anywhere
