API keys and scopes
Create scoped keys for agents and scripts, understand each scope, and review what automation did.
An API key is a workspace credential you issue to a program. It carries its own scopes, its own role cap, and its own audit trail — so you can see exactly what a given integration is allowed to do and what it actually did.
Create a key
Console → Settings → API keys → New key.
| Field | What it does |
|---|---|
| Name | What will use it — "Deploy agent", "CI pipeline". |
| Role cap | The strongest role the key may act as. Never owner. |
| Mode | live or test — useful for separating test harnesses from production agents. |
| Scopes | Exactly what the key may do. Nothing outside this list works. |
| Auto-approve | Off by default. When off, destructive actions queue for your approval. Billing spend always queues regardless. |
| Monthly spend cap | Ceiling on what this key can commit per calendar month. Blank means uncapped. |
The token appears once. Copy it into whatever the integration reads — for the
MCP server, ZP_API_KEY.
Scopes
Every scope is resource:action. A key needs the scope for the action it is
taking; there is no implicit escalation.
Sites
| Scope | Grants |
|---|---|
site:read |
List and inspect sites, logs, env vars. |
site:deploy |
Create a site, deploy, restart, start/stop. |
site:write |
Change env vars, config, domains, cron tasks. |
site:delete |
Delete a site. (approval-gated) |
Databases
| Scope | Grants |
|---|---|
database:read |
List and inspect databases, logs, backups. |
database:deploy |
Provision, start/stop/restart, back up. |
database:write |
Change database configuration. |
database:delete |
Delete a database. (approval-gated) |
Deployments
| Scope | Grants |
|---|---|
deployment:read |
Build history and build logs. |
deployment:write |
Cancel a running deployment. |
DNS
| Scope | Grants |
|---|---|
dns:read |
List zones and records. |
dns:write |
Create zones, add/update/delete records. |
| Scope | Grants |
|---|---|
mail:read |
List mail domains and mailboxes. |
mail:write |
Create mailboxes, reset passwords, suspend. |
Storage
| Scope | Grants |
|---|---|
storage:read |
List buckets and objects, presign downloads. |
storage:write |
Create buckets, upload, delete objects, rotate keys. (approval-gated) |
Billing
| Scope | Grants |
|---|---|
billing:read |
Read invoices, subscriptions, wallet balance. |
billing:spend |
Checkout, pay invoices, top up wallet. (always approval-gated) |
Workspace
| Scope | Grants |
|---|---|
org:read |
Read workspace settings and members. |
org:write |
Change workspace settings. (approval-gated) |
Scopes you cannot grant yourself are refused at creation: a key is capped by the
role of the person who minted it, so a developer cannot mint a
billing:spend key.
Role cap
The role cap bounds the key independently of scopes. A key issued by an owner
with roleCap: developer acts as a developer forever — promoting the owner later
does not widen the key.
Reviewing what automation did
Console → Settings → Agent approvals shows anything waiting on you. Approved, failed and rejected history is one tab away.
Every agent call is also written to the workspace audit trail with
actorType: api_key, the key's name, and the request id:
curl "https://api.falcon.zoophost.com/api/v1/agent/activity?actor=api_key" \
-H "Authorization: Bearer zp_live_…"
Rotating and revoking
Rotate issues a replacement with identical policy and revokes the old key in one step — the safest way to respond to a suspected leak. Revoke kills a key immediately; anything using it starts getting 401.
Revoking a key also disarms its queued approvals: a request still waiting for a human fails on replay instead of executing under a credential you have just withdrawn.
Revoked keys are kept in the list (collapsed) so the audit trail still resolves which key did what.
Key hygiene
- Give each integration its own key. Shared keys make the audit trail useless.
- Start with the fewest scopes that work. You can add more later, but a key that
never had
site:deletecannot be talked into deleting anything. - Leave auto-approve off unless the agent runs somewhere you trust to make irreversible decisions unsupervised.
- Set a spend cap on any key that can reach billing.
- api key
- scopes
- permissions
- role cap
- audit
- automation
Ready to use this
Everything the API provisions is a catalog plan you can see priced first.
- Same catalog the console reads
- INR pricing, GST included

