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:
npm install @vibiz/appThe 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:
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:
# 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:
| Capability | Provided through VIBIZ_APP_KEY | How your application uses it |
|---|---|---|
| Postgres Database | Injected via await vibiz.loadEnv() | Plain Postgres over the internet using DATABASE_URL |
| Sign-in | Injected via await vibiz.loadEnv() | Google and GitHub OAuth, passwords, magic links |
| AI Models | vibiz.ai | OpenAI-compatible gateway: chat, speech, images, and embeddings |
vibiz.email.send(…) | Outbound delivery from <mailbox>@<slug>.vibiz.app | |
| Files | vibiz.files.upload(…) | Storage up to 50 MB per file with permanent public URLs |
| Payments | vibiz.payments.checkout(…) | Hosted checkouts, subscriptions, customer portal links |
| Analytics | vibiz.track(…) | Server-side events; cookieless web tracking via snippet |
| Web Data | vibiz.actions.run(…) | Scrape pages, crawl websites, retrieve search results |
| Phone | vibiz.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.
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- Production: Contains live customer rows in Postgres, processes real money via card payments, and routes incoming webhooks to your live domains.
- 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:
vibiz devThe 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:
# 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.jsTrusting external domains
When your backend lives elsewhere, register its public URL so that analytics and sign-in endpoints accept requests from it:
vibiz domains add app.example.com --elsewhere
vibiz domains verify app.example.comOnce 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/appSDK 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 unauthorizederror. - Key rotation: If a key is compromised, rotate it from the CLI:
vibiz app-key rotate --grace 86400This 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.