# Auth and keys: PREVIZ developer concepts | AIM Previz

https://aimpreviz.com/developers/concepts/auth

[Previz](https://aimpreviz.com/) / [Developers](https://aimpreviz.com/developers) / Developer concepts

# Auth and keys

Published 4 Nov 2026Updated 5 Nov 2026by the PREVIZ team

How a program proves who it is to the PREVIZ door: a personal API key in a header today, what that key can reach, and how to bound it.

## A key is you, at a distance

Every call to https://mcp.aimpreviz.com carries a credential, and today that credential is a PREVIZ API key sent as an Authorization header: "Authorization: Bearer pvz_…". You mint keys in Account → API keys. A key is shown once, at the moment it is made, and PREVIZ keeps only a hash of it, so a lost key is revoked and replaced, never recovered. Minting asks for a sign-in from the last half hour, so a borrowed browser session cannot quietly become a standing machine credential.

A call with no credential, or a key that was revoked, is answered with HTTP 401 and a WWW-Authenticate challenge before any method runs, the handshake included. Only the checks that need no credential come before it: a refused web origin (403), a body that is not JSON (-32700) and a batch or malformed message (400, -32600). A program that sees a 401 should stop and ask its person for a key rather than retry.

## What a key reaches

A key whose access its owner has set reaches every project its owner may act on, owned, shared with them or in their organisation, at its owner's role there: a read needs at least viewer, anything else needs editor. A key made before access classes existed, whose access was never set, reaches only its owner's own projects, as it always did; team reach is given, never inherited. A key can also be limited to a list of projects, and then it reaches only those of them its owner may still act on. Ask list_projects first; it answers with exactly the ids this key can use, and any other project id is refused with PROJECT_UNREACHABLE and a sentence naming the cause.

A key holds only the access classes its owner gave it, set in Account → API keys → the key's Access: a new key holds read and write, and spend needs a monthly credit cap. tools/list shows only the tools a key holds, and a call to any other is refused with INSUFFICIENT_SCOPE. A key made before access classes existed keeps what it could do then (read, write, spend and live) until its owner sets its access; produce is given, never inherited.

Every operation in the reference declares the access class it needs (read, write, spend or live). The door enforces it per key on every call, so give an agent the narrowest key that does its job.

## The monthly credit cap

Each key can carry its own monthly credit cap, set by its owner, and a key whose access its owner has set spends only with one (CAP_REQUIRED says so otherwise). It is enforced on the server before any spend: a call that would take the key past its cap is refused with the cap, what has been spent this month and what remains, and nothing is charged. Every quote a capped key receives carries the same three numbers as keyBudget, so an agent can plan inside its budget instead of bouncing off it. The owner's credit balance stays the hard wall underneath; a cap is a limit, not a reserve.

## Test keys: the whole door, and no credit moves

Account → API keys mints two kinds of key. A test key starts pvz_test_ and runs every tool against a sandbox: it reaches only your sandbox project (PREVIZ opens one the first time the key is used, and list_projects names it), a render is a small fixture file kept in that project's storage, and what a tool would have charged is a row in a test ledger. No engine runs and no credit moves. Every answer through a test key carries testMode: true, and get_account says which project is the sandbox.

Everything around the render is the real thing, so an integration built against a test key behaves the same with a live one: a paid tool quotes first and runs once under a quoteToken or an idempotencyKey, the key's own monthly cap and spending agreements hold, a call past them answers input_required for a person's press, a take is a job that lands about twenty seconds after it starts, a production follows one fixed script (a priced plan and a free question, three takes, a priced ask on the third, then a settle that bills only what was made), and the same events arrive through events_since, the event stream and webhooks.

To walk the failure paths, put a marker in a prompt: sandbox:refuse makes the tool refuse before any charge, sandbox:pace answers RATE_LIMITED with a five-second wait, and sandbox:fail makes a take end in error with its test charge returned. simulate_event, a tool only a test key is shown, writes one event of any kind into the sandbox project's stream.

A test key can never reach a live project, whatever its project list or your role says, and a live key never reaches the sandbox project. A key's kind is fixed when it is minted: to go live, mint a live key. The sandbox keeps no list of meshes (check_mesh still completes one from its requestId), and a fixture is the same file whatever was asked for.

## Sign-in from an address alone

Coming next: Claude.ai and Claude Desktop, which add a server from its address alone. You will add PREVIZ as a custom connector and approve it on a PREVIZ sign-in page — no key to paste. Until that opens, use a client that can send a key.

When it opens, a sign-in will reach its person's own projects, confirm a spend only with a quote token or an idempotency key, and spend only under a monthly cap its person sets for that app.

## Browsers, logs and leaks

Calls from a server, a terminal or a desktop application carry no Origin header and are accepted. A call from a web page is accepted from PREVIZ's own sites, from a developer's own machine (localhost and loopback addresses) and from PREVIZ's desktop panels. A page with no web address of its own, which browsers send as the origin "null", is accepted too: a panel loaded from disk sends it, and so does a sandboxed frame or a data: address on any website, and nothing in the request tells them apart. Any other origin is refused with 403 before the credential is read.

So the origin rule is not what protects a key, and it does not have to be: the door takes no cookie and no session, so every call, from anywhere, needs the key itself. A key pasted into a web page is a key published to everyone who opens it, so call the door from a server and keep the key there.

Every tool call made with a key is written to its owner's activity log with the tool, the key and the credits it spent. Keep keys in an environment variable or your client's secret store, never in a file you commit, and revoke a key the moment it leaves the machine it was made for.

## The tools this is about

- **[`list_projects`](https://aimpreviz.com/developers/reference/list_projects)** — List projects
- **[`get_account`](https://aimpreviz.com/developers/reference/get_account)** — Read this connection's access
- **[`simulate_event`](https://aimpreviz.com/developers/reference/simulate_event)** — Fire a test event

### Other concepts

- [Quotes and money](https://aimpreviz.com/developers/concepts/money)
- [Projects and engine policy](https://aimpreviz.com/developers/concepts/policy)
- [Continuity](https://aimpreviz.com/developers/concepts/continuity)
- [Jobs and events](https://aimpreviz.com/developers/concepts/jobs)

[Developers home](https://aimpreviz.com/developers) [Tool reference](https://aimpreviz.com/developers/reference) [Mint a key](https://aimpreviz.com/account)
