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.
On this page 6 sections
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.
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:
- 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 for a breakdown of how branching prevents data loss.
- Billing operates in sandbox mode: Payment tools like
vibiz_paymentsrun 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. - 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 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:
{
"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.
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:
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:
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:
vibiz keys create audit-bot --read-allVia the API:
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.
# Allow an agent to read the production database schema and rows
vibiz keys access key_123 allow database.production:readThrough HTTP, submit a PATCH request with the array of permission names:
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--devflag 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.
# Pull the development environment into local files
vibiz dev
# Run a local process injected with development credentials
vibiz dev -- npm run devIf 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 and 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.