Authentication, Credentials & IP Allowlisting

Every automated integration with CentralNic Reseller rests on two things: who you are (your credentials) and where you are connecting from (the IP allowlist). Get both right and the rest of your integration just works; get either wrong and your very first connection fails before a single command runs. This page is the reference the quick starts lean on — and the first place to look when a connection is refused.

It is written for the developer or operations person setting up API access, or debugging it at 2 a.m. You will find how credentials and API users fit together, exactly how the allowlist is enforced, the security practices worth adopting from day one, and a focused troubleshooting section for when a connection will not come up.

By the End of This Page You Will Know

• How your account login and least-privilege API users differ, and how a user actually authenticates
• How the IP allowlist is enforced across every API gateway, and what changes when you move from OT&E to production
• The security practices — credential storage, rotation, least privilege, environment separation — that keep access safe as you scale
• How to diagnose a failed connection fast: rejected credentials, a blocked IP, or an expired session

First Things First

Authentication secures a funded, configured account — it is not the account setup itself. If you have not yet funded your account, created users and enabled security, work through Your First Day as a CentralNic Reseller first; it applies to every integration method.

How Credentials Work

CentralNic Reseller separates the account from the users who act on it, and understanding that split is the key to everything else on this page.

• Your account is the top-level identity — the one tied to your balance, your contract and your Control Panel login.
• Users live beneath the account. Each user has its own password and its own permissions, so you can give a person or a service exactly the access it needs and nothing more.

For automation you should almost always connect as a dedicated API user, not as the account itself. That way a leaked or rotated integration credential never touches your master login, and you can scope each user to just the operations it performs.

How a User Logs In

A user authenticates with the account name and the username joined by a colon, plus that user’s own password:

login    = accountname:username
password = (that user's password)

This same format is used everywhere a user connects — the Control Panel, the EPP gateway (<clID>accountname:username</clID>), and the HTTPS, SOAP, XML-RPC and XRRP gateways alike. If you connect as the account itself, the login is simply the account name with no colon.

Least-privilege Users via ACL

Permissions are governed by an Access Control List (ACL). You can set specific rights per user and per group — which objects a user may reach, and which operations it may perform on them. The simplest place to manage this is the Control Panel, under your account menu (top-right) → User management, where you can list every user and group and edit their ACL permissions.

Prefer to automate it? Users and groups can also be managed over the API with AddUser (create a user or group), ModifyUser (change a password, or add and remove group membership), DeleteUser, StatusUser and QueryUserList.

One User per Integration

Give each integration — WHMCS, your custom platform, a monitoring script — its own API user, scoped to only what it needs. If you ever have to rotate or revoke one, you affect that integration alone, and your audit trail tells you which system did what.

See ACL Users & Groups for the full permission model, and the Password Policy for the rules every password must meet (10–64 characters, with upper- and lower-case letters, a number and a special character).

The IP Allowlist

On top of credentials, CentralNic Reseller offers an IP allowlist so that only connections from addresses you trust can reach your account over the API. It is a second, independent layer: a valid login from an un-allowlisted address is still refused.

What It Covers, and What It Does Not

The allowlist applies to the API gateways — EPP, SOAP, HTTPS, XRRP and XMLRPC. When it is enabled, every connection over those protocols is checked against your list.

Two settings live side by side in the Control Panel, and it is worth keeping them straight:

• IP Whitelist — controls access to the API gateways (the one this page is about).
• IP Whitelist WI — controls access to the Control Panel login. The API allowlist does not affect Control Panel access, and vice versa.

The Rules That Matter

• The allowlist is disabled by default — until you turn it on, connections are not filtered by IP.
• You can add up to five (5) IPv4 addresses or ranges. Ranges from /24 to /30 are accepted (for example 192.0.2.42 or 192.0.2.42/27).
• Use your external IPv4 address(es) — the address your servers present to the internet. Internal or reserved addresses will not work.
• Changes take effect as soon as a connection is re-established; connections that are already open keep working until they reconnect.

Where To Set It

1. Open the Control Panel and go to your account menu (top-right) → Settings → Account Data → Security.

2. Switch IP Whitelist from Use Default to Yes to activate it for the API gateways.

3. Enter the external IPv4 address(es) or range(s) the servers running your integration connect from — up to five.

4. Click Save Changes. The new list applies on the next reconnection.

OT&E and Production Usually Connect From Different IPs

Your test servers and your live servers rarely share the same external address. Add the addresses of your production hosts to the allowlist before you cut over, or the first live connection will be refused even though your OT&E setup worked perfectly. And avoid allowlisting a dynamic (dial-up) address that changes — it can lock you out later.

For gateway hostnames and ports (which differ between OT&E and production), read the current values from API → API Gateways in the Control Panel rather than copying them from anywhere else — that page always reflects the correct endpoints for your account. See API Security and IP Whitelist for the full detail.

How Authentication Is Sent on Each Session

How your credentials travel depends on the gateway, and this matters when you are chasing an intermittent failure.

• EPP is session-oriented: you open a TLS connection, send Session:Login once, run your commands, then Session:Logout. Treat sessions as long-lived and design around the server’s connection and lifetime limits — see the EPP Integration Guide.
• HTTPS checks your password on every request by default. For a busier integration you can open a persistent session instead: send StartSession with persistent = 1, receive a sessionid, and pass that session ID on subsequent requests rather than the password. Close it with StopSession when you are done.

Sending the password only once, at the start of a session, is both faster and more secure than repeating it on every call. See HTTPS Session Handling for the exact StartSession / StopSession flow.

OT&E Uses Its Own Password

Your OT&E credentials are separate from production. The OT&E login is your standard account login, but you set its password from the live Control Panel under Account → Settings → Passwords. Keep the two environments’ credentials distinct so a test never touches live data.

Security Best Practice

The mechanics above are only as strong as how you handle them. A few habits keep API access safe as your integration grows.

• Never hard-code credentials. Keep them out of source code, config files committed to version control, container images and log output. Read them at runtime from a secret store or environment injected by your deployment tooling.
• Rotate credentials on a schedule — and immediately if one may have been exposed. Dedicated API users make this painless: rotate one user’s password with ModifyUser without disturbing anything else.
• Apply least privilege. Scope each API user through its ACL to only the objects and operations it needs, so a compromised credential has a limited blast radius.
• Separate OT&E and production configuration. Use distinct credentials and distinct config for each environment, and make it structurally impossible to point a test at production (or the reverse). Different secret paths per environment beat a single toggle.
• Layer your defences. Enable the IP allowlist on the API gateways, and protect Control Panel logins with two-factor authentication. Credentials, allowlisting and 2FA each stop a different kind of attack.

Treat a Leaked Credential as Compromised

If an API password ever lands somewhere it should not — a shared log, a public repository, a screenshot — rotate it immediately with ModifyUser rather than hoping it went unnoticed. Because each integration has its own user, you can do this without downtime for anything else.

Troubleshooting Connection Failures

When a connection will not come up, the cause is almost always one of three things: your credentials, your IP, or your session. Work through them in that order.

Symptom you see	Likely cause	Fix
Login rejected / authentication failed, even with the right password	Wrong login format, or the wrong password for that identity	Use accountname:username and that user’s password; connect as the account (no colon) only if you mean to
Authentication fails only in OT&E	No OT&E password has been set	Set the OT&E password from the live Control Panel (Account → Settings → Passwords)
Password change refused	New password does not meet the policy	Use 10–64 characters with upper- and lower-case letters, a number and a special character
Connection refused or times out immediately, but credentials are correct	The connecting IP is not on the allowlist	Add your external IPv4 address to IP Whitelist; it applies on reconnect
Worked yesterday, fails today after no code change	Your external IP changed, or you are connecting from a new/added host	Add the current external IP; avoid allowlisting dynamic addresses
Session invalid / “must log in again” mid-run	The session expired or was closed	Reconnect and start a fresh session (EPP re-login, or a new HTTPS StartSession)

Credentials Rejected

If the login itself is refused, check the format before the password: the colon-joined accountname:username is required for a user, and the password must be that user’s own, not the account password. Confirm you are pointed at the right environment — an OT&E login needs its OT&E password, set from the live Control Panel. If you are rotating a password, remember the policy rules: 8–32 characters including upper- and lower-case letters, a number and a special character.

IP Not on the Allowlist

A refused or immediately-dropped connection despite correct credentials is the classic signature of an allowlist block. Confirm the external IPv4 address your server actually presents to the internet (not an internal or NAT address) is listed under Settings → Account Data → Security → IP Whitelist. Remember that the list applies on reconnect, so a change will not affect a connection that is already open — and that OT&E and production typically connect from different addresses, which is the most common reason a working OT&E setup fails on its first production call.

Session and Timeout Issues

If a connection authenticates but later reports that you must log in again, the session has ended. On HTTPS, a persistent session opened with StartSession does not last forever — reconnect and call StartSession again to obtain a fresh sessionid. On EPP, sessions are subject to idle and lifetime limits, so build in a keep-alive and a periodic re-login rather than assuming one session lasts indefinitely; the EPP Integration Guide covers those limits in detail.

Change One Variable at a Time

When a live command fails where the identical OT&E command worked, it is nearly always the endpoint, the credentials or the allowlist — the three things that differ between environments. Confirm each in isolation and the culprit reveals itself quickly.

What To Do Next

With authentication and the allowlist understood, you are ready to build, test and go live with confidence.

API SecurityIP allowlisting across the EPP, SOAP, HTTPS, XRRP and XMLRPC gateways.

HTTPS Session HandlingOpen a persistent session with StartSession and reuse the session ID.

ACL Users & GroupsThe full permission model for least-privilege API users.

IP WhitelistSet up the allowlist for your API gateways in the Control Panel.

EPP Integration GuideSessions, commands and the connection limits registrars build around.

Moving from OT&E to ProductionSwap endpoints and credentials, and re-check the allowlist before go-live.