thelastapi
Get started free

One env var for everything: VIBIZ_APP_KEY explained

A single environment variable, VIBIZ_APP_KEY, powers your entire backend—connecting database, sign-in, AI, email, files, payments, and analytics.

On this page 7 sections

You can configure your entire backend using a single environment variable, VIBIZ_APP_KEY, instead of managing dozens of individual service tokens. Setting this one server secret gives your application immediate access to serverless Postgres, user sign-in, an OpenAI-compatible AI gateway, transactional email, storage files, card payments, web analytics, web scraping, and phone capabilities. At runtime, the client SDK uses this single credential to authenticate all built-in calls directly or hydrate standard environment variables into your process on boot.

This guide explains what VIBIZ_APP_KEY is, how it works across runtimes and hosting providers, and how it simplifies building and deploying software.

Why configure your app with one key instead of ten

Every new production service usually demands its own account, a unique API key, a webhook secret, and a dashboard for monitoring usage. A typical modern stack requires:

  • A database connection string (DATABASE_URL)
  • Public and private keys for authentication
  • An API key for transactional email
  • Separate API tokens for each AI lab
  • Storage credentials and bucket names for file uploads
  • Secret keys and webhook signing secrets for card payments
  • Tracking snippets and project tokens for analytics

This operational sprawl creates failure points. If an API token expires or an environment variable is mistyped in production, the application crashes. When you need to rotate credentials, you must update multiple control panels and redeploy services in lockstep.

The one-key model consolidates this surface area. Instead of coordinating disparate secrets, your server needs only VIBIZ_APP_KEY. To learn more about consolidating your architecture, read our breakdown on one key for your whole app: the one-API stack for indie builders and how to stop juggling API keys: one key instead of ten services.

How VIBIZ_APP_KEY works in your code

The app key format looks like vz_app_…. It is scoped strictly to a single project and environment. You can interact with your project services through the @vibiz/app package or via plain HTTP calls.

Using the @vibiz/app SDK

Install the client library:

Terminal
npm install @vibiz/app

The library runs on Node 20+, Bun, Deno, and edge runtimes. It reads VIBIZ_APP_KEY from process.env. If your code requires traditional environment variables—such as DATABASE_URL for an ORM or VIBIZ_AUTH_* for sign-in handlers—call loadEnv() when your server initializes:

TypeScript
import { vibiz } from '@vibiz/app';
import OpenAI from 'openai';

// Injects DATABASE_URL, VIBIZ_AUTH_*, VIBIZ_WEBHOOK_SECRET into process.env
await vibiz.loadEnv();

// Call the AI gateway using standard OpenAI clients
const openai = new OpenAI(vibiz.ai);

// Send transactional email
await vibiz.email.send({
  to: 'ana@example.com',
  subject: 'Welcome to Acme',
  text: 'Your account is ready.',
});

// Upload a file to project storage (returns a permanent URL)
const avatar = await vibiz.files.upload(imageBuffer, {
  name: 'avatar.png',
  contentType: 'image/png',
});

// Create a checkout session for card payments
const { url } = await vibiz.payments.checkout({
  lookup_key: 'pro-monthly',
  user: 'usr_123',
  success_url: 'https://example.com/success',
  cancel_url: 'https://example.com/pricing',
});

For more implementation details on each method, consult the @vibiz/app documentation.

Calling the API without an SDK

If your stack cannot add an npm package or runs in another language, use the HTTP endpoints directly. Every action is exposed under /v1/app and authenticates with Authorization: Bearer $VIBIZ_APP_KEY:

Terminal
# Fetch all environment variables as JSON, dotenv, or shell formats
curl https://thelastapi.dev/v1/app/env?format=json \
  -H "Authorization: Bearer $VIBIZ_APP_KEY"

# Send an email via plain HTTP
curl https://thelastapi.dev/v1/app/actions/email.send \
  -H "Authorization: Bearer $VIBIZ_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":{"to":"ana@example.com","subject":"Welcome","text":"Hi Ana"}}'

What capabilities are covered by the app key

The table below summarizes what VIBIZ_APP_KEY provisions and accesses across your project:

CapabilityProvided through VIBIZ_APP_KEYHow your application uses it
Postgres DatabaseInjected via await vibiz.loadEnv()Plain Postgres over the internet using DATABASE_URL
Sign-inInjected via await vibiz.loadEnv()Google and GitHub OAuth, passwords, magic links
AI Modelsvibiz.aiOpenAI-compatible gateway: chat, speech, images, and embeddings
Emailvibiz.email.send(…)Outbound delivery from <mailbox>@<slug>.vibiz.app
Filesvibiz.files.upload(…)Storage up to 50 MB per file with permanent public URLs
Paymentsvibiz.payments.checkout(…)Hosted checkouts, subscriptions, customer portal links
Analyticsvibiz.track(…)Server-side events; cookieless web tracking via snippet
Web Datavibiz.actions.run(…)Scrape pages, crawl websites, retrieve search results
Phonevibiz.phone.send(…), call(…)Send texts, initiate spoken alerts, or run voice agents

Every service operates independently. As covered in Use one service, you can use only the AI gateway, just payments, or the entire list without altering the authentication pattern.

Development vs production environments

Every project has two isolated environments: development and production. Each maintains its own distinct VIBIZ_APP_KEY.

Text
Project: Acme App
├── Production  ──> VIBIZ_APP_KEY (vz_app_prod_...) ──> Real DB, live card payments, live domains
└── Development ──> VIBIZ_APP_KEY (vz_app_dev_...)  ──> DB branch (empty rows), test payments, localhost
  1. Production: Contains live customer rows in Postgres, processes real money via card payments, and routes incoming webhooks to your live domains.
  2. Development: Built for local machines and agents. It provisions an isolated database branch containing identical schema tables but zero production rows. Payment calls run in test mode, and sign-in automatically trusts http://localhost:3000.

When you run local development commands:

Terminal
vibiz dev

The CLI provisions the development environment and writes your local development variables—including the development app key—to .env.development.local. To learn more about this workflow, read our guide on development vs production environments for small teams and the details in Keys and environments.

Using the app key on any hosting platform

Your application does not need to deploy on thelastapi hosting. If you host on a third-party server, a container instance, or a serverless platform, you only need to provide VIBIZ_APP_KEY in that host's environment settings.

Hydrating variables at boot

If you use non-Node runtimes or external frameworks that expect a standard .env file before executing, hydrate the process using the CLI or a shell pipeline:

Terminal
# Using the CLI runner
npx @vibiz/cli run -- python server.py

# Or during a container build step
npx @vibiz/cli env pull --format dotenv -o .env.production

# Or using shell evaluation on server start
eval "$(curl -fsS -H "Authorization: Bearer $VIBIZ_APP_KEY" https://thelastapi.dev/v1/app/env?format=shell)" && exec node server.js

Trusting external domains

When your backend lives elsewhere, register its public URL so that analytics and sign-in endpoints accept requests from it:

Terminal
vibiz domains add app.example.com --elsewhere
vibiz domains verify app.example.com

Once the domain verification TXT record is validated, the service accepts traffic and dispatches webhook events to your running servers.

Security boundaries and key rotation

The VIBIZ_APP_KEY is strictly a server-side secret.

  • Browser safety: The @vibiz/app SDK throws an error if it detects execution inside a browser environment (window !== undefined). Public frontend operations, such as client-side web analytics, use a dedicated, read-only analytics site key instead.
  • Project scoping: An app key can only access routes and resources within its own project and environment. Attempting to manage account-level settings, billing details, or other projects returns a 401 unauthorized error.
  • Key rotation: If a key is compromised, rotate it from the CLI:
Terminal
vibiz app-key rotate --grace 86400

This command provisions a new VIBIZ_APP_KEY immediately. The --grace flag allows the previous key to remain valid for a specified window (defaulting to 24 hours / 86,400 seconds) so that running instances and background workers transition without downtime.

Next: explore how usage is tracked in Billing and credits, or connect your application to your project services using @vibiz/app. If you do not yet have an account, create one at thelastapi.dev/start.

Frequently asked questions

Can I use VIBIZ_APP_KEY in client-side frontend code?

No, the app key is a server secret that gives full access to your project database, email, and billing credits. The `@vibiz/app` SDK refuses to run in the browser to prevent leaks; frontend analytics use a separate public site key.

How does my app receive database connection strings if I only set VIBIZ_APP_KEY?

Calling `await vibiz.loadEnv()` at application boot fetches your project configuration securely from `/v1/app/env` and populates `DATABASE_URL` and other service variables directly into `process.env`. Alternatively, you can use `npx @vibiz/cli run -- <command>` to inject them before your process starts.

What happens to running apps when I rotate VIBIZ_APP_KEY?

Rotating a key with `vibiz app-key rotate` creates a new secret while keeping the old key active for a grace period (24 hours by default). This window allows you to update your hosting provider's environment variables and restart processes without downtime.