# Full access vs Limited API keys for AI agents

> API keys for AI agents should use Limited access to let models build, test, and deploy without risking production secrets or live money.

**API keys for AI agents should use Limited access so autonomous tools can build, test, and deploy software without reading production secrets or moving live money.** In thelastapi, you assign agents a Limited key that defaults to an isolated development environment containing schema-only database branches and sandbox billing. If an agent attempts an owner-only action—such as processing live refunds or viewing production secrets—the API halts execution with a structured error that links directly to a human-in-the-loop approval screen.

Choosing the right permissions model lets you safely connect tools like Claude Code, Codex, and Cursor to your infrastructure. This guide covers how Full access and Limited keys differ, how scoped permissions work, and how agents safely navigate permission boundaries.

## What can Full access and Limited keys do?

When you log in through the CLI (`vibiz login`) or authorize an agent connection via remote Model Context Protocol (MCP) at `https://thelastapi.dev/mcp`, you choose the access tier for that key. Every key is prefixed with `vz_sk_…`.

- **Full access (`access: owner`):** This is the default when creating keys manually as an owner. A Full-access key can perform every action on the account. It can read production environment variables, provision or revoke API keys, remove custom domains, connect external hosting providers, execute live refunds, initiate bank withdrawals, and delete projects.
- **Limited key (`access: agent`):** Built specifically for agents. A Limited key can create projects, trigger deployments, run web data actions, send emails, generate AI completions, inspect usage, and manage the development environment. It cannot read production variables, revoke keys, remove domains, or move real money.

Here is how permissions break down between key types:

| Capability | Limited key | Full-access key |
| --- | --- | --- |
| Create projects, deploy code, and promote previews | Yes | Yes |
| Run actions, call AI models, and view usage | Yes | Yes |
| Read and update development environment values | Yes | Yes |
| Inspect production environment variable names | Yes (`?names=1`) | Yes |
| Read production environment secret values | No | Yes |
| Create, modify, or revoke API keys | No | Yes |
| Add new domains to projects | Yes | Yes |
| Remove domains or disconnect external hosts | No | Yes |
| Process live refunds, cancellations, and withdrawals | No | Yes |
| Run test-mode payments, refunds, and simulations | Yes | Yes |

A key created for an agent can be managed at any time from the Keys page in the console, or switched via the CLI. To learn more about setting up your workspace, read about using [one API key for an AI agent: hosting, database, email, payments and models](https://thelastapi.dev/blog/one-api-key-for-ai-agent).

## Why keep agents on Limited access?

Handing an autonomous agent a Full-access key creates unnecessary operational risk. Modern coding agents run terminal commands, execute shell scripts, and parse external files. If an agent has access to raw production database credentials or live payment keys, a prompt injection or an unexpected tool call can corrupt active customer accounts.

Limited keys enforce safety by defaulting requests to the **development environment**:

1. **Production data stays isolated:** A Limited key interacting with the database accesses an isolated branch containing your tables and schema, but zero customer rows. Read [why agents should never touch production rows](https://thelastapi.dev/blog/agents-never-touch-production-rows) for a breakdown of how branching prevents data loss.
2. **Billing operates in sandbox mode:** Payment tools like `vibiz_payments` run in test mode automatically when called by a Limited key. The agent can create products, generate test checkout links, and simulate webhooks, but it cannot drain funds or issue unauthorized customer refunds.
3. **Company formation is simulated:** An agent can draft filings or test workflows using `vibiz company simulate`, but submitting a legal filing with fees requires manual owner confirmation.

By letting an agent iterate inside development, you can confidently [let an AI agent build and deploy a full-stack app](https://thelastapi.dev/blog/agent-build-deploy-full-stack-app) from scratch without supervising every routine file write or test build.

## How agents handle permission checks and secrets

When a Limited key calls an endpoint reserved for the account owner, the API does not simply fail silently. It answers with an HTTP `403 forbidden` error containing the code `owner_only` and structured machine-readable metadata:

```json
{
  "error": "forbidden",
  "details": {
    "reason": "owner_only",
    "permission": "database.production:read",
    "key_id": "key_123",
    "grant_url": "https://thelastapi.dev/keys/key_123/allow?permission=database.production:read",
    "console_url": "https://thelastapi.dev/projects/prj_123/settings",
    "key_url": "https://thelastapi.dev/keys?key=key_123",
    "next_step": "Open the grant_url to allow this permission for this key, or perform the action yourself in console_url."
  }
}
```

When an agent encounters this error, it parses `details.grant_url` and gives you the link. You open the page, review what the key attempted to do, and choose whether to allow just that permission, grant read access, or upgrade the key to Full access. Once approved, the agent retries the call.

### Passing secrets without pasting them into chat

You should never paste third-party API tokens directly into an agent's chat window. If the agent needs a secret configured in your app's environment, it uses the `vibiz_request_secret` tool or calls `POST /v1/projects/:id/secret-link`.

```bash
curl -X POST https://thelastapi.dev/v1/projects/prj_123/secret-link \
  -H "Authorization: Bearer $LIMITED_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "STRIPE_SECRET_KEY", "environment": "production", "kind": "env"}'
```

The API returns a secure `console_url`. The agent outputs the link to you:

```text
Paste STRIPE_SECRET_KEY here: https://thelastapi.dev/projects/prj_123/secrets/new?name=STRIPE_SECRET_KEY&env=production&kind=env . It goes straight to thelastapi, never through this chat.
```

You paste the value directly into the console. The secret is encrypted and injected into your app's environment without ever exposing the raw string to the model context.

## Creating and modifying keys

You can provision and audit keys using the CLI or the REST API. Creating or modifying keys requires an existing Full-access key.

### Creating an agent key

Create a Limited key for a background task or CI agent:

```bash
vibiz keys create growth-agent --limited
# Returns: vz_sk_... (shown once)
```

To create a read-only reporting agent that can view production metrics, logs, and database schemas without making modifications, use `--read-all`:

```bash
vibiz keys create audit-bot --read-all
```

Via the API:

```bash
curl -X POST https://thelastapi.dev/v1/api-keys \
  -H "Authorization: Bearer $OWNER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "growth-agent", "access": "agent"}'
```

### Granting granular permissions

Rather than elevating a key to Full access, you can grant specific permissions to a Limited key using `grants`. 

```bash
# Allow an agent to read the production database schema and rows
vibiz keys access key_123 allow database.production:read
```

Through HTTP, submit a `PATCH` request with the array of permission names:

```bash
curl -X PATCH https://thelastapi.dev/v1/api-keys/key_123 \
  -H "Authorization: Bearer $OWNER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"grants": ["database.production:read", "env.production:read"]}'
```

Common granular grants include:

| Permission | Group | What it allows |
| --- | --- | --- |
| `database.production:read` | Database | Read production database tables and rows |
| `env.production:read` | Production settings | Read production environment variable values |
| `env.production:write` | Production settings | Set or remove production variables |
| `payments.live:read` | Payments | Inspect live payment transactions and webhooks |
| `payments.live:write` | Payments | Issue live refunds, update products, or withdraw |
| `social.live:write` | Social | Publish live social posts or ad campaigns |
| `company:read` | Company | Access filing documents and tax identifiers |

You can review all available permissions from your terminal with `vibiz keys permissions`.

## Managing environments between keys

Your project automatically maintains two environments: `production` and `development`. 

- A **Full-access key** defaults to `production`. Any action run without the `--dev` flag applies directly to live traffic, production databases, and active payment channels.
- A **Limited key** defaults to `development`. All commands run against sandboxed copies unless an explicit permission has been granted.

```bash
# Pull the development environment into local files
vibiz dev

# Run a local process injected with development credentials
vibiz dev -- npm run dev
```

If an agent needs to restart with a clean testing environment, run `vibiz dev --reset`. The existing sandbox is discarded, and a new database branch is spun up mirroring production's current schema.

For more technical details on how environment isolation works across tools, refer to the documentation on [Keys and environments](https://thelastapi.dev/docs/keys) and [Agents](https://thelastapi.dev/docs/agents).

Get started by running `vibiz keys create <name> --limited` for your next agent, or inspect your machine's active key configuration with `vibiz whoami`.

## Frequently asked questions

### Can a Limited key change its own permissions?

No, an API key cannot elevate its own access level. Adjusting presets or adding granular grants requires a Full-access key or manual owner approval on the Keys page.

### What happens if an agent tries to read a production secret using a Limited key?

The API returns HTTP 403 with `reason: "owner_only"` and provides a `grant_url` for the human owner. If the agent only needs to configure a secret, it can call `vibiz_request_secret` to generate a direct console link where the owner pastes the value securely.

### How does a Limited key behave differently with the database?

By default, a Limited key interacts only with the development database branch, which mirrors the production schema but contains no rows. To allow an agent to query live customer data, you must explicitly assign the `database.production:read` permission.

---

Published 2026-11-15 · https://thelastapi.dev/blog/full-access-vs-limited-agent-keys
