API permissions by area: read or write, and which permission each task needs

The short answer: each API area has two permissions, :read to read and :write to change, for example dns:read and dns:write. A key only does what you granted when you created it. If it lacks the permission an operation needs, the API answers 403 with the code insufficient_scope.

The areas and their status

Area	Permissions	Status
Account	account:read, account:write	Read available; write has no operations yet
Catalogue	catalog:read, catalog:write	Read available; write has no operations yet
Domains	domains:read, domains:write	Available
DNS	dns:read, dns:write	Available
Hosting	hosting:read, hosting:write	Available
E-mail	email:read, email:write	Available
WordPress	wordpress:read, wordpress:write	Coming soon
VPS servers	vps:read, vps:write	Available
Billing	billing:read, billing:write	Available
Support	support:read, support:write	Available
Extras	extras:read, extras:write	Available
Reseller	reseller:read, reseller:write	Read available; write has no operations yet
SMS	sms:read, sms:write	Available
Automatic notices	webhooks:read, webhooks:write	Coming soon

You can already tick the "Coming soon" areas, but they only take effect once their operations exist.

Which permission each task needs

You want to...	The key needs
See your domains and nameservers	domains:read
Change nameservers, transfer lock or auto-renewal	domains:write
Register, renew or transfer a domain	domains:write and billing:purchase
Add, change or delete DNS records	dns:write
See the list of services (hosting and servers)	hosting:read
Create a database or a subdomain	hosting:write
Create mailboxes or forwarders	email:write
See and restart a VPS	vps:read and vps:write
See invoices, orders and quotes	billing:read
Pay an invoice from your credit	billing:pay
Open and reply to support tickets	support:write
Send SMS	sms:write

A known trap: the list of services, GET /v1/services, uses hosting:read even for servers. The server operations themselves use vps:read. A program that manages a VPS usually needs both.

What needs no area permission

GET /v1/ping and GET /v1/openapi.json need no key at all. GET /v1/token and GET /v1/limits work with any valid key, and they are the quickest way to confirm which permissions a key has.

A permission is missing: now what?

The API's own advice for insufficient_scope is to create a key with that permission. Do it on the API page in My MozOut, swap the key in your program and revoke the old one, as described in looking after your keys.

There is also a separate group of permissions, off by default, for anything that can cost money or give full access: paying, buying, cancelling, reinstalling a VPS, logging in to cPanel. They are covered in sensitive permissions and the spending limit. As a rule, prefer :read whenever the program only reads.

Creating a key? Tick only the areas your program needs, and write access only where it really is required.

Create a key

Categories

Categories