thelastapi
Console
Getting started

Keys and environments

Full-access, Limited and app keys; production and development; who may do what.

Open as .md

A key can do everything the owner can, unless the person chose Limited. Signing in (vibiz login, or Authorize for an MCP client) asks which: Full access is pre-selected; Limited builds and runs but never holds a production secret nor moves live money. A Limited key works against a separate development environment that holds none of production's data, and gets a link for the person whenever something needs more. The owner can change any key between Full and Limited on the Keys page.

The keys

KeyLooks likeHeld byCan
Full-access key (default)vz_sk_…, access: ownerthe CLI, the MCP server, CI, a personeverything the owner can: projects, deploys, actions, email, AI, usage, the production env, keys, domains, connecting hosts, live refunds and withdrawals, deleting
Limited keyvz_sk_…, access: agentan agent the person chose to limitcreate projects, deploy, promote, run actions, send email, use AI, read usage, get the development env, everything in development. Never the production env, keys, removing a domain or live money
Console sessiona cookiea person signed in at thelastapi.devthe access of their account: whoever opened the account is its owner
App keyvz_app_… (VIBIZ_APP_KEY)the running appits own project and environment only: env, AI, actions, email, events, payments for its users
Project AI keyvz_ai_…the app (VIBIZ_AI_API_KEY)the AI gateway, billed to the project

New keys have full access unless the owner picks Limited (creating, changing and revoking keys needs a full-access key):

Terminal
vibiz keys create ci                    # full access, shown once
vibiz keys create growth-agent --limited  # a Limited key
vibiz keys access key_… limited         # change it afterwards (full | read | limited)
vibiz keys revoke key_…
Terminal
curl https://thelastapi.dev/v1/api-keys -H "Authorization: Bearer $OWNER_KEY" \
  -H 'content-type: application/json' -d '{"name":"growth-agent","access":"agent"}'
# → 201 { "id": "key_…", "secret": "vz_sk_…", "access": "agent", … }   the secret is returned once
curl -X PATCH https://thelastapi.dev/v1/api-keys/key_… -H "Authorization: Bearer $OWNER_KEY" \
  -H 'content-type: application/json' -d '{"access":"owner"}'
# → 200 { "id": "key_…", "access": "owner", … }   a key never changes its own access

Keys made before full access became the default keep the access they had.

Name a key per person or agent: usage breaks down by key (vibiz usage --by api_key).

Keys and environments

  • Full-access key (vz_sk_…, access owner): what the MCP server and the CLI hold by default, since signing in pre-selects Full access. It can do everything the owner can: projects, deploys, actions, AI, usage, production secrets, live money, keys, domains, connecting hosts, deleting.
  • Limited key (access agent): what the person gets by choosing Limited when they sign in (or set later on the Keys page). Builds and runs: projects, deploys, actions, AI, usage, the development env, everything in development. Never a production secret, never live money: production refunds, cancels, withdrawals, payment settings, keys, removing domains and connecting hosts answer 403 owner_only. The fix for owner_only is a person, not a retry: give them details.console_url to do it themselves, or details.key_url to give this key full access (or they sign in again choosing Full access).
  • App key (vz_app_…, VIBIZ_APP_KEY): the running app's one secret, per environment.

Development env (vibiz_dev_env, vibiz dev): its own database branch with the app's tables and no production rows, its own sign-in (trusts http://localhost:3000), its own AI key, and VIBIZ_WEBHOOK_SECRET once a development webhook is set. write_to puts the values in an env file without showing them.

The project id: ./vibiz.json { "project_id": "prj_…" } in a linked app folder, or vibiz_project_status for the list. Read it instead of asking the user.

Environments

Every project has two environments. env (or --dev in the CLI) picks one; it defaults to production for full-access keys and development for Limited keys.

productiondevelopment
Databasethe real onea branch with the same tables and no rows
Sign-inreal users; trusts the live domainsits own users; trusts http://localhost:3000
AIthe project's keya second key, billed to the project
Paymentslive money, 7-day holdtest mode, test cards, no hold, simulate
Companya real filing, real feesnothing filed, nothing charged, simulate
Whofull access for secrets and moneyanyone on the account, Limited keys included

Hosting, analytics, replay and email have no development copy (a local run shouldn't count as visits or send mail from the live address).

Terminal
vibiz dev                     # create it once and write .env.development.local (names printed, values not)
vibiz dev -- npm run dev      # pass the values to a command, no file
vibiz dev --reset             # throw the copy away; the next `vibiz dev` branches again

Over HTTP: POST /v1/projects/:id/dev (create, 202), GET /v1/projects/:id/dev (status: none | provisioning | ready | failed), GET /v1/projects/:id/dev/env (the values, 409 until ready), DELETE /v1/projects/:id/dev.

Getting the production env to the app

  1. thelastapi hosting: automatic. Every key is pushed to the host and kept in sync.
  2. A connected host: the owner connects Vercel, Netlify, Render, Railway, Fly.io, Heroku, Cloudflare Workers or Pages, or GitHub Actions once (vibiz hosts add <host> <app>); thelastapi writes the env there whenever it changes, rotations included. Vercel is verified live; the others are in beta.
  3. One key, any host: put only VIBIZ_APP_KEY in the host and load the rest at boot.
TypeScript
import { vibiz } from '@vibiz/app';
await vibiz.loadEnv(); // the app's env into process.env
Terminal
eval "$(curl -fsS -H "Authorization: Bearer $VIBIZ_APP_KEY" \
  https://thelastapi.dev/v1/app/env?format=shell)" && exec node server.js

GET /v1/app/env?format=json|dotenv|shell|docker. Before any of these, the app's domain is added (vibiz domains add app.example.com --elsewhere; a Limited key may, and sign-in then trusts it once its TXT record proves it or the owner confirms it) so sign-in and analytics accept it. The project needs no thelastapi hosting at all: any one service works alone (Use one service).

The app key

  • One per project and environment, put in that environment's env with VIBIZ_API_URL. A development key reads only the development env, and its events are not recorded.
  • It works only for its own project: account routes answer 401.
  • Rotate with vibiz app-key rotate (production needs an owner). The new key is pushed to thelastapi hosting and every connected host; the old one keeps working for a day by default (--grace <seconds>, 0 ends it now). The new secret is never printed.

What a Limited key can and can't do

Limited keyFull-access key
Projects, deploys, actions, AI, email, usageyesyes
Development env valuesyesyes
Production env values (GET /projects/:id/env)names only (?names=1)yes
Add the app's domainsyes (sign-in trusts one once its TXT record proves it)yes
Create, change or revoke keys, remove domains, connect hostsnoyes
Live refunds, cancels, withdrawals, payment settingsnoyes
Rotate the production app keynoyes

A Limited key hitting an owner route gets 403 forbidden with details.reason: "owner_only", details.permission (what it lacks), details.grant_url (/keys/<id>/allow?permission=…: a page for this key to allow just that, read everything, or everything), details.console_url (where the person does it), details.key_url (the Keys page with this key highlighted, /keys?key=<id>) and details.next_step naming them. Retrying with the same key works only once the permission is allowed.

Permissions: Read everything, or one at a time

A Limited key can be given more without full access:

  • Read everything (preset: "read_all"): reads all of it, production data and settings included (the production database, production variables, live payment details, a company's full details, exports), and changes nothing live.
  • Single permissions (grants): exactly the ones it needs, e.g. only database.production:read.
PermissionGroupWhat it allows
database.production:readDatabaseread the production database (the app's users' data)
app_users:writeDatabasesign out one of the app's users
env.production:readProduction settingsread production variables
env.production:writeProduction settingsset and remove production variables
app_key.production:readProduction settingssee the production app key
app_key.production:writeProduction settingsrotate the production app key
auth.production:writeProduction settingschange production sign-in settings
exports.production:readProduction settingsexport production data and download secret values
projects:writeProjectsturn the public live page on or off
domains:writeDomains & hostingremove domains
domains.registration:writeDomains & hostingsee and change a bought domain's owner details, auto-renew and transfer code, and move it between projects
dns:writeDomains & hostingchange a domain's DNS records
hosting:writeDomains & hostingconnect and disconnect hosts
payments.live:readPaymentssee live payment details and webhook secrets
payments.live:writePaymentsrefund, cancel, change live products and webhooks, withdraw, connect your own payment account
billing:writeBilling & keyschange billing settings and the card
keys:writeBilling & keyscreate, revoke and change API keys
ai_keys:writeBilling & keysset, change and remove AI provider keys
company:readCompanysee a company's full details and documents
company:writeCompanysend tax ids, sign, answer, pay for and submit filings
connectors.live:writeConnectorschange live connectors and approve their calls
email.marketing:writeEmailchange marketing email settings
email.inbox:writeEmailadd, change and delete mailboxes and forwarding, and move a domain's mail
social.live:writeSocialapprove, publish, cancel live posts and ad changes
phone:writePhonebuy and release phone numbers
search:writeSearchconnect Google and Bing and change search settings

When a Limited key is refused, the error names the permission and links to it: details.permission (* when only full access will do), details.grant_url (a page for this one key: what it asked for, when it was last used, and Allow just this, Read everything, Full access or Choose exactly), details.key_id, and details.console_url (where a person does it by hand). An agent gives the user grant_url, then retries once it is allowed. The CLI prints it as "Allow it for this key: …" and opens it when a person is at the terminal.

Terminal
vibiz keys access                               # what this key may do, and the link to change it
vibiz keys access key_… read                     # Read everything (full | read | limited)
vibiz keys access key_… allow database.production:read
vibiz keys permissions                          # every permission, in plain words
vibiz keys create reporter --read-all
Terminal
curl -X PATCH https://thelastapi.dev/v1/api-keys/key_… -H "Authorization: Bearer $OWNER_KEY" \
  -H 'content-type: application/json' -d '{"grants":["database.production:read"]}'

PATCH /v1/api-keys/:id takes {"access"}, {"preset": "full" | "read_all" | "limited"} or {"grants": [...]} (GET /v1/api-keys/permissions lists them). It needs keys:write; a Limited key never gives more than it has, and never changes its own access. Signing in (vibiz login, an MCP client's Authorize) offers Full access, Read everything or Limited.

Whatever the access, a few things are the person's own in the browser, not a key permission: verifying their identity to withdraw, connecting their own Stripe account, and approving a sign-in. Nobody can read card numbers.

A secret never passes through a chat. When an app needs one (a third-party API key, a host token), the agent asks thelastapi for a link and gives it to the person, who pastes the value there:

Text
Paste STRIPE_SECRET_KEY here: https://thelastapi.dev/projects/prj_…/secrets/new?name=STRIPE_SECRET_KEY&env=production&kind=env . It goes straight to thelastapi, never through this chat.
  • From an agent: vibiz_request_secret { project_id, name, env?, kind? } returns that console_url and the sentence to pass on. Over HTTP: POST /v1/projects/:id/secret-link { name, environment?, kind? }.
  • kind: env (default) is one of the app's own variables; connector a connector's key (name = its variable); ai the project's own lab key (name google); host a host token, so thelastapi keeps that host's env in sync (name vercel, netlify…).
  • The app's own variables are write-only: names are listed (vibiz env vars, GET /v1/projects/:id/env/vars), a value is never returned to any key. They are in the env the app loads (await vibiz.loadEnv(), vibiz env pull) as process.env.NAME, and in every connected host. Setting a production one needs full access (a Limited key gets the link instead). In a terminal: vibiz env set <NAME> asks for the value hidden; vibiz env link <NAME> prints the link; vibiz env unset <NAME> removes it.

Errors

CodeStatusWhenNext step
unauthorized401missing, unknown or revoked key; an app key on an account routecheck VIBIZ_API_KEY / VIBIZ_APP_KEY
forbidden + owner_only403a Limited key without the permission (details.permission)give the person details.grant_url (allows it for this key), or details.console_url to do it themselves
dependency_not_ready409the development copy isn't ready yetpoll GET /projects/:id/dev
not_found404the project isn't on this accountcheck ./vibiz.json