ZoophostDocs

API keys and scopes

Create scoped keys for agents and scripts, understand each scope, and review what automation did.

API & agents4 min read

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.

Mail

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:delete cannot 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
See the plans behind the API
Still stuck? Open a ticket from Support tickets in the console, or email [email protected]. Include the service name, the exact error and what you already tried.