Permissions

Preview

Connected applications are currently available to selected accounts only.

A permission is an area and a level: read, change or delete. The application asks for them by name, such as dns:write, and the consent screen shows the area and level with the description below. The list of refused requests names them the same way.

The permissions

Permission	On the consent screen	What it allows	Rating
account:read	Account: Read	Reads your profile: name, address and account settings.	Read only
billing:read	Billing: Read	Reads invoices, subscriptions and outstanding amounts.	Read only
domain:read	Domains: Read	Reads your domains, their terms and their nameservers.	Read only
dns:read	DNS: Read	Reads your DNS zones and every record in them.	Read only
dns:write	DNS: Change	Creates, changes and deletes DNS records. That decides where your domains and your email point. It covers the records that decide which servers receive your email (MX) and which may send email in your name (SPF, DKIM, DMARC), and the ones that decide who can get certificates for your domains (CAA and _acme-challenge).	Changes data
mail:read	Email: Read	Reads your mailboxes and their settings, for example info@your-domain.com.	Read only
mail:write	Email: Change	Creates and changes mailboxes, aliases, forwards, vacation replies and the catch-all, for example contact@your-domain.com, and can switch addresses off. A forward may point outside your domains, so email sent to you can be passed on to any address.	Changes data
mail:delete	Email: Delete	Deletes mailboxes together with every email in them, as well as aliases and forwards, and switches off the catch-all.	Critical
handle:read	Domain contacts: Read	Reads your domain contacts and whether they are verified, with name, address, email address and phone number only for your own default contacts.	Read only
handle:write	Domain contacts: Change	Adds and changes domain contacts; for a contact that is the owner or admin contact of one of your domains, only its phone and fax numbers. Sends a contact a verification code by email or SMS, for example to owner@your-domain.com, and confirms it with the code you pass on.	Changes data

These ten are all there is. An application that asks for a permission ITSH knows but does not grant, such as buying or deleting domains, has that part of its request dropped before the consent screen, and a request with nothing left is refused. A request naming a permission ITSH does not know at all is refused as a whole with invalid_scope.

No mail permissions without a DPA

If your account is recorded as not needing a data processing agreement (DPA) and you have not accepted its current version, ITSH does not grant mail:read, mail:write and mail:delete. The consent screen names them and says why.

• A new connection does not get them, not even later. Accept the DPA in the portal under "DPA", then connect the application again so it can ask for them.
• A connection that already holds them keeps them, but cannot use them once its access token is renewed, within an hour at the latest. If it holds nothing but mail permissions, it gets no new token at all until you accept the DPA. After that it uses them again from its next renewal, without connecting again.

Deleting cannot be undone

mail:delete is rated Critical for a reason: nothing brings deleted data back, not even revoking the access afterwards. A deleted mailbox takes every message in it along.

How the levels combine

• Change includes read in the same area. dns:write can also read DNS, and mail:write can read mail settings.
• Nothing else includes anything. mail:delete does not include mail:write or mail:read, and no permission in one area reaches another.
• Some tools need several permissions. A tool appears only when the connection holds all of them, as the next table shows.

Tools that need more than one

Tool	Needs
dns_record_list	domain:read, dns:read
dns_record_create, dns_record_update, dns_record_delete	domain:read, dns:write
mail_account_list, mail_catchall_get, mail_dns_status	mail:read, domain:read
mailbox_create, mail_forward_create, mail_catchall_set	mail:write, domain:read
mail_account_delete	mail:read, mail:delete
mail_catchall_disable	mail:delete, mail:write, domain:read
mail_dns_apply, mail_dns_replace	mail:write, dns:write, domain:read

mail:delete on its own makes no tool available. Every other tool needs exactly one permission. The DNS, email and contact pages list theirs; these four read your account and have no page of their own:

Tool	What it does	Needs
account_get	Shows your account: its number, name, type, email address and country	account:read
domain_list	Lists your domains with their status and registration period, including domains registered elsewhere that ITSH handles email for	domain:read
domain_get	Shows one of your domains	domain:read
subscription_list	Lists your subscriptions with their status and current paid period, including recently ended ones	billing:read

domain_list and domain_get appear only once your account holds a domain. The three public tools and the two about the connection itself, grant_get and grant_revoke, need none.

What to allow

Task	Allow
Look at DNS records	domain:read, dns:read
Change DNS records	domain:read, dns:write
Set up mailboxes and forwards	domain:read, mail:write
Set up mail DNS records	domain:read, mail:write, dns:write
Keep domain contacts current	handle:write

What's next

• Connecting an application for the consent screen
• DNS tools, Email tools and Contact tools for each tool