# Keys and environments

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

**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):

```bash
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_…
```

```bash
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**.

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

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

```ts
import { vibiz } from '@vibiz/app';
await vibiz.loadEnv(); // the app's env into process.env
```

```bash
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](https://thelastapi.dev/docs/use-one)).

## 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 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. only `database.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` | Email | change marketing email settings |
| `email.inbox:write` | Email | 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.

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

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

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

```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](https://thelastapi.dev/docs/connectors)'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

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