Access and Authentication

URL

The HTTP API is available at: https://api.cloudns.net/
Note: For security reasons, you should always send API requests using HTTPS.

Authentication

All requests require the following authentication parameters:

auth-id: Api user ID (See the instructions below for finding your API ID) or sub-auth-id: Api sub user ID (See the instructions below for finding the API ID) or sub-auth-user
auth-password: The password for API user ID or for API sub user ID.

How to Create an API User ID

1. Log in to your ClouDNS account.
   
   
2. From the navigation menu, click on “API & Resellers”.
   
   
3. In the “API Users” section, click on “Add new user”.
   
   
4. Fill in the required fields:
   
• auth-password – This will be the password you’ll use to authenticate API requests.
  
• IP address – This is optional. Leave it blank to allow connections from any IP address. If you want to restrict access to specific IPs, enter them here.
  
5. Click Save.

Once saved, the system will automatically generate the auth-id (API user ID), which will appear in the users table.

Use the generated auth-id and the password you provided to authenticate API requests.

Note: Leaving the IP address field empty allows API access from any IP address. Only fill this in if you want to limit access to specific IPs for security.

How to Create an API Sub-User

1. Log in to your ClouDNS account.
   
   
2. From the navigation menu, click on “API & Resellers”.
   
   
3. In the “API Sub-Users” section, click on “Add new sub-user”.
   
   
4. Fill in the form with the following fields:
   
• sub-auth-user – Optional. You can specify a custom username for the sub-user.
• auth-password – Required. This will be used for authenticating API requests.
• IP address – Optional. Leave it blank to allow access from any IP. Specify IPs only if you want to restrict access.
• DNS zones – Required. Enter a number that defines how many DNS zones the sub-user is allowed to create.
• DNS records – Required. Enter a number that limits how many DNS records the sub-user can create.
• Mail forwards – Required. Enter a number indicating how many mail forwards the sub-user can manage.
• DNS Failover checks – Required. Enter a number that specifies how many failover checks the sub-user is allowed to set up.
• Access level – Choose between Read and write or Read only
5. Click Save.

The system will generate a sub-auth-id, which will appear in the sub-users table.

To authenticate with the API, the sub-user can use either the sub-auth-id or sub-auth-user, along with the password you set.

Note: Sub-users have more limited access compared to full API users. Their permissions and access can be customized during creation.

Errors

When the authenctication of API user is not correct, any API request will fail with the following status and statusDescription:

{"status":"Failed","statusDescription":"Invalid authentication, incorrect auth-id or auth-password."}

In case the credentials of API sub user are invalid, the following status and statusDescription will be returned:

{"status":"Failed","statusDescription":"Invalid authentication, incorrect sub-auth-id, sub-auth-user or auth-password."}

Note: These are example errors in JSON format.