API token abilities

This page lists the API token scopes, called abilities, that a team API token can hold, with the API operations each one allows.

• You choose a token’s abilities when you create it in Settings › , then API tokens. The form starts with every read and check ability selected; Read only, Everything except delete, Full access and Clear change the whole selection.
• A token’s abilities can’t be changed later. To give a script other abilities, create a new token and revoke the old one.
• A request whose token lacks the ability an operation needs is refused with a 403 error.

Ability	Name in the portal	API operations it allows	Can be chosen in the portal
host:read	Read Hosts	List domains and IPs Get a domain or IP	Yes
host:create	Create Hosts	Add a domain or IP	Yes
host:update	Update Hosts	Update a domain or IP	Yes
host:delete	Delete Hosts	Delete a domain or IP	Yes
data-source:read	Read Data Sources	List blocklists Get a blocklist	Yes
data-source-group:read	Read Monitoring Profiles	List check profiles Get a check profile	Yes
data-source-group:create	Create Monitoring Profiles	Create a check profile	Yes
data-source-group:update	Update Monitoring Profiles	Update a check profile	Yes
data-source-group:delete	Delete Monitoring Profiles	Delete a check profile	Yes
alert:read	Read Alert Destinations	List alert channels Get an alert channel	Yes
alert:create	Create Alert Destinations	Add an alert channel	Yes
alert:update	Update Alert Destinations	Send a test alert Update an alert channel	Yes
alert:delete	Delete Alert Destinations	Delete an alert channel	Yes
alert-group:read	Read Contact Groups	List delivery hours Get delivery hours	Yes
alert-group:create	Create Contact Groups	Add delivery hours	Yes
alert-group:update	Update Contact Groups	Update delivery hours	Yes
alert-group:delete	Delete Contact Groups	Delete delivery hours	Yes
blacklist:check	Check Blacklist	Start a blocklist check	Yes
blacklist:read	Read Blacklist Status	Get blocklist check status	Yes
certificate:check	Check Certificates	Start a certificate check	Yes
certificate:read	Read Certificate Status	Get certificate check status	Yes
certificate:agent	Private Certificate Agent	No API operation needs it.	Yes
deliverability:check	Check Email Deliverability	Run an email authentication check	Yes
deliverability:read	Read Email Deliverability	Get an email authentication check	Yes
metrics:read	Read Prometheus Metrics	Get Prometheus metrics	Yes
email-verification:check	Check Email Verification	No API operation needs it.	No

Note

metrics:read, which lets Prometheus scrape your metrics, also needs the Business or Enterprise plan. On the Professional plan, GET /api/v1/metrics answers 403 even when the token holds the ability.

Notes

• certificate:agent can be selected, but no team API operation uses it. A private certificate agent signs in with its own hrca_ token, not a team API token.
• The ability names keep the API’s internal words: host is a domain or IP, data-source a blocklist, data-source-group a check profile, alert an alert channel, alert-group delivery hours and deliverability email authentication.

Related

• Authentication and API tokens shows how to create a token and send it.
• Limits and defaults lists the API rate limits.
• Credit costs lists the checks that use credits.
• Webhook events lists the callbacks an API check can send.
• Plans and limits shows which plans include Prometheus metrics.