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 on every token route and answers 403. On reseller calls the body is a ResellerError; on Domain management calls it is a ClientError:
ip_not_allowed(reseller calls) or"IP not allowed"(Domain management calls): the call comes from an address outside the whitelist.ip_whitelist_misconfigured(reseller calls) or"IP whitelist misconfigured"(Domain management calls): the whitelist cannot be read, so every call is refused (fail-closed). Fix the whitelist in the client area.
On reseller calls, read error.code as for any other refusal; on Domain management calls, read message.
401 and 403
Answer | Meaning | What to do |
|---|---|---|
401 | The token is missing, invalid or expired. The body is {"message": "…"} (MessageError). | Check the header and the token; do not retry blindly. |
403 ip_not_allowed / "IP not allowed" | The call comes from an address outside the token’s IP whitelist. Reseller calls: ResellerError; Domain management calls: ClientError. | Call from a whitelisted server, or update the whitelist. |
403 ip_whitelist_misconfigured / "IP whitelist misconfigured" | The token’s IP whitelist cannot be read, so every call is refused. Reseller calls: ResellerError; Domain management calls: ClientError. | Fix the whitelist in the client area. |
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. |
403 forbidden | The token’s user lacks the permission the call needs. | Use a user with managedomains for changes. |
403 on Domain management | The token is not valid for this account, the user lacks the permission, or the domain’s status does not allow the change. The body is {"success": false, "message": "…"} (ClientError). | Read message. |