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
| Key | Looks like | Held by | Can |
|---|---|---|---|
| Full-access key (default) | vz_sk_…, access: owner | the CLI, the MCP server, CI, a person | everything the owner can: projects, deploys, actions, email, AI, usage, the production env, keys, domains, connecting hosts, live refunds and withdrawals, deleting |
| Limited key | vz_sk_…, access: agent | an agent the person chose to limit | create 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 session | a cookie | a person signed in at thelastapi.dev | the access of their account: whoever opened the account is its owner |
| App key | vz_app_… (VIBIZ_APP_KEY) | the running app | its own project and environment only: env, AI, actions, email, events, payments for its users |
| Project AI key | vz_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):
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_…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 accessKeys 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_…, accessowner): 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 answer403 owner_only. The fix forowner_onlyis a person, not a retry: give themdetails.console_urlto do it themselves, ordetails.key_urlto 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.
| production | development | |
|---|---|---|
| Database | the real one | a branch with the same tables and no rows |
| Sign-in | real users; trusts the live domains | its own users; trusts http://localhost:3000 |
| AI | the project's key | a second key, billed to the project |
| Payments | live money, 7-day hold | test mode, test cards, no hold, simulate |
| Company | a real filing, real fees | nothing filed, nothing charged, simulate |
| Who | full access for secrets and money | anyone 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).
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 againOver 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
- thelastapi hosting: automatic. Every key is pushed to the host and kept in sync.
- 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. - One key, any host: put only
VIBIZ_APP_KEYin the host and load the rest at boot.
import { vibiz } from '@vibiz/app';
await vibiz.loadEnv(); // the app's env into process.enveval "$(curl -fsS -H "Authorization: Bearer $VIBIZ_APP_KEY" \
https://thelastapi.dev/v1/app/env?format=shell)" && exec node server.jsGET /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>,0ends it now). The new secret is never printed.
What a Limited key can and can't do
| Limited key | Full-access key | |
|---|---|---|
| Projects, deploys, actions, AI, email, usage | yes | yes |
| Development env values | yes | yes |
Production env values (GET /projects/:id/env) | names only (?names=1) | yes |
| Add the app's domains | yes (sign-in trusts one once its TXT record proves it) | yes |
| Create, change or revoke keys, remove domains, connect hosts | no | yes |
| Live refunds, cancels, withdrawals, payment settings | no | yes |
| Rotate the production app key | no | yes |
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. onlydatabase.production:read.
| Permission | Group | What it allows |
|---|---|---|
database.production:read | Database | read the production database (the app's users' data) |
app_users:write | Database | sign out one of the app's users |
env.production:read | Production settings | read production variables |
env.production:write | Production settings | set and remove production variables |
app_key.production:read | Production settings | see the production app key |
app_key.production:write | Production settings | rotate the production app key |
auth.production:write | Production settings | change production sign-in settings |
exports.production:read | Production settings | export production data and download secret values |
projects:write | Projects | turn the public live page on or off |
domains:write | Domains & hosting | remove domains |
domains.registration:write | Domains & hosting | see and change a bought domain's owner details, auto-renew and transfer code, and move it between projects |
dns:write | Domains & hosting | change a domain's DNS records |
hosting:write | Domains & hosting | connect and disconnect hosts |
payments.live:read | Payments | see live payment details and webhook secrets |
payments.live:write | Payments | refund, cancel, change live products and webhooks, withdraw, connect your own payment account |
billing:write | Billing & keys | change billing settings and the card |
keys:write | Billing & keys | create, revoke and change API keys |
ai_keys:write | Billing & keys | set, change and remove AI provider keys |
company:read | Company | see a company's full details and documents |
company:write | Company | send tax ids, sign, answer, pay for and submit filings |
connectors.live:write | Connectors | change live connectors and approve their calls |
email.marketing:write | change marketing email settings | |
email.inbox:write | add, change and delete mailboxes and forwarding, and move a domain's mail | |
social.live:write | Social | approve, publish, cancel live posts and ad changes |
phone:write | Phone | buy and release phone numbers |
search:write | Search | connect 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.
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-allcurl -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.
Secrets by link
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:
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 thatconsole_urland 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;connectora connector's key (name = its variable);aithe project's own lab key (namegoogle);hosta host token, so thelastapi keeps that host's env in sync (namevercel,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) asprocess.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
| Code | Status | When | Next step |
|---|---|---|---|
unauthorized | 401 | missing, unknown or revoked key; an app key on an account route | check VIBIZ_API_KEY / VIBIZ_APP_KEY |
forbidden + owner_only | 403 | a 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_ready | 409 | the development copy isn't ready yet | poll GET /projects/:id/dev |
not_found | 404 | the project isn't on this account | check ./vibiz.json |