Every request to the my.host API needs one credential: a personal access token. Create one in the control panel under My account → API access. API keys are deprecated: new ones can no longer be created, and existing keys keep working.| Credential | Header | Can do |
|---|
| Personal access token | Authorization: Bearer mh_pat_… | Only the permissions chosen for the token, and never more than the user who created it. Expires after the period you choose (7 days to a year), or has no expiry date. Optionally limited to IP addresses or subnets. |
| API key (deprecated) | API-Key: <key> | Everything the user who created it may do. Optionally limited to IP addresses. |
A token without an expiry date suits integrations that run unattended, such as WHMCS or automatic certificate renewal. Such a token is revoked after 12 months without use; the user who created it gets an e-mail 30 days before. Using the token again keeps it.To replace an API key, create a token and put it where the key was: a token also works in the API-Key header.Send one of the two, not both. Clients that can only send a bearer credential may also send an API key as Authorization: Bearer <key>. Clients that can only send an API-Key header, such as older versions of our WHMCS module, may send a token there: API-Key: mh_pat_….A credential belongs to the user who created it. When the main user of the account changes that user's permissions, the change applies at once to that user's API keys and tokens.API key (deprecated)#
Personal access token#
A token is shown once, when you create it: we only store a fingerprint (hash) of it. You can revoke a token at any time in the control panel; it stops working immediately.Token permissions (scopes)#
When you create a token you choose, per section, what it may do. In the API these are scopes of the form <section>:<level>, for example domains:read or vps:write. Every level includes read for the same section.| Level | In the control panel | Allows |
|---|
read | View | Viewing data. |
write | Change | Changes that cost nothing but take effect at once, such as DNS records, starting or restarting a VPS, firewall rules, replying to a ticket. |
purchase | Order | Anything that costs money: orders, renewals, upgrades, reserving a floating IP. |
critical | High impact | Actions you cannot undo and confidential data: deleting or cancelling, reinstalling, restoring a backup, changing the owner of a domain name, auth codes, root and rescue passwords, managing users. |
The sections are domains, domains-profiles, domains-nameservers, domains-dns-templates, vps, vps-ssh-keys, vps-floating-ips, certificates, order, account-profile, account-paymethods, account-invoices, account-tickets, account-users and account-affiliate.Errors#
| Status | Meaning |
|---|
401 Unauthorized | No credential, an unknown or expired credential, a revoked token, or a key or token used from an IP address outside its whitelist. |
403 Forbidden | The credential is valid but may not call this endpoint: the user lacks the permission, or the token lacks the scope. |
With 401 and 403 the response has a WWW-Authenticate header as described in RFC 6750. For a missing scope it names the scope:Security best practices#
Keep credentials confidential. Treat API keys and tokens as passwords. Do not share them or put them in client-side code.
Give a token only what it needs. Choose the fewest sections and levels, and a short lifetime. Only give High impact when the integration really needs it.
Revoke what you no longer use. Revoke a token or deactivate an API key in the control panel as soon as you suspect it has leaked.
Modified at 2026-11-13 09:40:29
