An Amóni API key does only what its scopes allow. A scope is a named area of the account, and a key carries the set you tick when you create it. The habit worth keeping is least privilege: give each key the narrowest set that lets its job run, so a key that leaks or a script that misbehaves can only reach what it was ever meant to.
The scopes
read covers listing and viewing every resource. Each write area is its own scope, and choosing a write scope includes reading that area, so you never tick read alongside a write to get view access.
| Scope | What a key with it can do |
|---|---|
read |
List and view everything: servers, VMs, IPs, monitors, projects, operations. |
servers.write |
Power, reinstall and rescue bare-metal servers; set tags and labels; read a reinstall's root password. |
vms.write |
Power, rebuild, rename and re-password cloud instances; snapshots, backups, firewall, cloud-init. |
ips.write |
Change reverse DNS on your addresses. |
monitors.write |
Create, edit, pause and delete uptime monitors. |
sshkeys.write |
Add and remove keys in your stored SSH key set. |
projects.write |
Create projects and move resources into them. |
webhooks.write |
Create webhooks and send test events. |
vpcs.write |
Manage private networks. |
network.write |
Announce and withdraw blackhole routes. |
bgp.write |
Manage BGP sessions. |
colo.write |
Raise datacenter access and remote-hands requests. |
orders.write |
Place orders. An order generates an invoice, so this one spends money. |
Choosing the set
Work backwards from what the key does. A monitoring dashboard that only draws graphs wants read and nothing else. A CI job that reinstalls a server wants read and servers.write. A Terraform run that manages servers, addresses and cloud instances wants read, servers.write, ips.write and vms.write. If you are unsure whether a key needs a scope, leave it off; adding it later is one edit, and a call that lacks it fails loudly rather than quietly doing too much.
Ordering sits on its own for a reason. orders.write is the only scope that costs money, because an order raises an invoice. Paying that invoice is deliberately not in the API at all, so even an ordering key cannot charge a card. Keep orders.write off every key that does not exist to buy things.
When a scope is missing
A call your key is not scoped for does not half-succeed. It answers 403, and the body names the scope to add:
{
"success": false,
"error": "This API key is missing the `servers.write` scope. Create a key with that scope in the portal under Account → API Keys.",
"code": "insufficient_scope",
"required_scope": "servers.write"
}Read code to branch in your own tooling, and required_scope to see exactly what to grant.
Two more limits on a key
Scopes decide what a key may do. Two other settings decide when and from where.
- The allowed source IPs are required, and they bind the key to the addresses it may be called from. A key scoped wide but locked to one CI runner is still a small target.
- An expiry is optional. A key you set to lapse in ninety days is one you cannot forget to rotate.
Rotation is a revoke and a recreate. Revoke next to a key stops it immediately, so anything still using it breaks at once. Create the replacement first, move your job onto it, then revoke the old one.
Questions we get
- Does a write scope include reading? Yes. A
servers.writekey can read servers without also holdingread. Tickreadonly for a key that reads and nothing more. - Can I change a key's scopes after creating it? No. Scopes are fixed at creation. To change them, create a new key and revoke the old one.
- Is there a scope for billing or invoices? No. Reading billing and paying invoices stay in the portal, off the API surface entirely.
- What is the smallest useful key? A
readkey locked to one address, for a dashboard or an export. It can see everything and change nothing.
Still stuck?
Open a support ticket with the key name and the required_scope from a 403. We can confirm what the key holds and what the route needs.