Every call is authenticated with a personal API token, sent as a Bearer token.
Bearer token
Authorization: Bearer <your-token>Create tokens in the client area under API Tokens. A token is a secret: keep it on your servers, never in a browser, a mobile app or a public repository. If one leaks, delete it in the client area and create a new one.
One account per token
A token is bound to one account and acts with the permissions its user has on that account. There is no separate scope list: a token cannot be narrowed to fewer permissions than its user. To limit what an integration can do, give it a user with fewer permissions.
Permissions
Permission | Allows |
|---|---|
domains | Reading: price list, availability checks, domain state, charges, and the read-only Domain management calls. |
managedomains | Changes and anything that moves money: register, transfer, renew, restore, and the Domain management changes (nameservers, contacts, EPP code, lock, WHOIS privacy, auto-renew). |
Each operation in the reference shows the permission it needs. The account must also be enabled for the reseller programme, with credit enabled.
IP whitelist
When you create a token you can restrict it to a list of IP addresses. Use it for production tokens: your servers call from known addresses. The whitelist is checked first, on every call, and refuses with 403:
ip_not_allowed: the call comes from an address outside the whitelist.ip_whitelist_misconfigured: the whitelist cannot be read, so every call is refused (fail-closed). Fix the whitelist in the client area.
401 and 403
Refusals use the standard error envelope; branch on code:
Answer | Meaning | What to do |
|---|---|---|
401 unauthenticated | The token is missing, invalid or expired. | Check the Authorization header and the token; do not retry blindly. |
403 ip_not_allowed | The call comes from an address outside the token’s IP whitelist. | Call from a whitelisted server, or update the whitelist. |
403 ip_whitelist_misconfigured | The token’s IP whitelist cannot be read, so every call is refused. | Fix the whitelist in the client area. |
403 client_token_required, token_not_api_enabled, token_not_client_scoped | The token is not a personal API token of an account. | Create a token in the client area (API Tokens) and use that. |
403 client_access_revoked | The token’s user no longer has access to the account. | Use a token of a user who still has access. |
403 client_cancelled | The account is cancelled. | Contact SupportHost. |
403 forbidden | The token’s user lacks the permission this call needs; permission names it. | Ask the account owner to grant it, or use another token. |
403 domain_not_active | The domain’s status doesn’t allow this change right now; domain_status names it. Not a permission problem. | Wait until the domain is active, or renew or restore it first. |
403 not_reseller | The account is not enabled for the reseller API. | Contact SupportHost. |
403 credit_disabled | Credit is disabled for the account. | Contact SupportHost. |