API Access Token Permissions Reference
Table of Contents
- Which permissions can a token have?
- What do the access levels allow?
- How does limiting to specific resources work?
- How do I read a Permission Denied error?
- Which permissions does a common task need?
- Have more questions?
A scoped API access token has a separate permission for each type of resource in your account, such as zones, domains, or certificates. Each permission is set to No access, Read-only, or Full access. Four permissions can also be limited to specific domains or zones. Scoped access tokens are available on the Teams plan and higher. To create one, see API Access Token.
Which permissions can a token have?
The Identifier column is the name the API uses for the permission in error messages.
| Permission | Identifier | What it covers | Access levels | Limit to specific resources |
|---|---|---|---|---|
| Account | account |
Account and identity endpoints | No access, Read-only | No |
| Billing | billing |
Billing endpoints | No access, Read-only | No |
| Certificates | certificates |
Sectigo and Let’s Encrypt certificates | No access, Read-only, Full access | Yes, by domain |
| Contacts | contacts |
Contacts, including domain registrants | No access, Read-only, Full access | No |
| Domain Research | domain_research |
Domain research status checks | No access, Read-only | No |
| Domains | domains |
Domains, including DNSSEC, email forwarding, and pushes | No access, Read-only, Full access | Yes, by domain |
| Platform | platform |
Platform statuses, messages, and metadata | No access, Read-only, Full access | No |
| Registrar | registrar |
Registrations, transfers, renewals, delegation, auto-renewal, and WHOIS privacy | No access, Read-only, Full access | Yes, by domain |
| Templates | templates |
Templates | No access, Read-only, Full access | No |
| Webhooks | webhooks |
Webhooks | No access, Read-only, Full access | No |
| Zones | zones |
DNS records, secondary, forward, and reverse zones, and applying one-click services and templates | No access, Read-only, Full access | Yes, by zone |
The Domain Research permission appears only on accounts with the Domain Research API.
What do the access levels allow?
| Access level | Identifier | Allows |
|---|---|---|
| No access | Not used | Nothing. Requests for this resource type are rejected. |
| Read-only | read |
Requests that read the resource. |
| Full access | write |
Requests that read or change the resource. Full access also satisfies requests that only need Read-only. |
How does limiting to specific resources work?
For Certificates, Domains, Registrar, and Zones, you can choose between:
- All of that resource type, including ones added to the account later.
- Selected specific domains or zones. The token can only reach the ones you select.
The smallest unit you can select is a domain or a zone. A token cannot be limited to a single subdomain or a single DNS record. Permission for a zone covers every record in it, including records for subdomains.
When a token is limited to specific resources, the /domains and /zones list endpoints return only those resources.
How do I read a Permission Denied error?
A request that needs a permission the token does not have returns HTTP 403 with a message such as:
Permission Denied. Required Scope: zones:{zone_name}:write
The message has three parts, separated by colons:
- The permission identifier from the table above, here
zones. - The resources it applies to:
*for all of them, or{domain_name}or{zone_name}for one specific domain or zone. The placeholder is shown as is, not replaced with the name from your request. - The access level identifier:
readorwrite.
To fix it, edit the token on the API & Access page and give it that permission. For other error messages, see API Errors.
Which permissions does a common task need?
Some tasks need a permission on all resources of that type. A token limited to selected domains or zones cannot do them.
| Task | Permission | Works with selected domains or zones? |
|---|---|---|
| Create, update, or delete DNS records, including TXT records for DNS validation | Zones: Full access | Yes, for the selected zones |
| Read DNS records | Zones: Read-only | Yes, for the selected zones |
| List domains in the account | Domains: Read-only | Yes. The list includes only the selected domains. |
| Add a domain to the account | Domains: Full access | No, needs all domains |
| Check whether a domain is available | Registrar: Read-only | No, needs all domains |
| Register a domain, or transfer one in | Registrar: Full access | No, needs all domains |
| Renew a domain | Registrar: Full access | Yes, for the selected domains |
| Enable or disable WHOIS privacy or auto-renewal | Registrar: Full access | Yes, for the selected domains |
| Manage webhooks | Webhooks: Full access | Not applicable |
Have more questions?
If you have additional questions or need any assistance with API access token permissions, contact support, and we will be happy to help.