Subscription API guide

ReleaseVersion 1.2

2.
The latest Subscription API guide is available here: https://docs.safedns.com/books/subscription-api/page/subscription-api-guide

---

Introduction

SafeDNS Subscription API is designed to give you an easy and fast way for automatic creation of new user’s accounts in SafeDNS cloud service from the internal systems of an ISP or a developer. Also, you can use this API to manage base settings of a user like his email, password, applied filtering profile.

Description

API developer (provider) is provided with a public key, that is used for authentication. All requests are made through HTTPS via GET requests. Each request must contain public key with the name of a parameter key.

Public key is provided with separate email and should not be available in open access.

API address: https://www.safedns.com/provider_api/

API call example: curl "https://www.safedns.com/provider_api/METHOD_NAME?key=PUBLIC_KEY&mandatory_parameter=VALUE&optional_parameter=VALUE"

Table of available methods

Table of values for the plan parameter

Methods & parameters

Red parameters are mandatory.

Blue parameters are optional.

1. subscribe

Registers a User in the system with the provided credentials, and sets the expiration date of the account to +1 year from the current date.

1 mandatory parameter is used:

4 optional parameters can be used:

Example: curl "https://www.safedns.com/provider_api/subscribe?key=PUBLIC_KEY&password=StrongPassword123&login=ACCOUNT_NAME&email=email@example.com&plan=PREMIUM&customer=John Doe"

Response is returned in JSON format:

{
	"response": {
		"status": "ok",
		"data": {
			"username": "username",
          	"email": "email",
          	"plan": "tariff_name"
		}
	}
}

2. subscribe_plans

Lists Reseller’s available billing plans.

Example: curl "https://www.safedns.com/provider_api/subscribe_plans?key=PUBLIC_KEY"

Response is returned in JSON format: 

{
	"response": {
		"status": "ok",
		"data": {
			"plan1": "tariff_name1",
			"plan2": "tariff_name2"
		}
	}
}

3. activate

Sets status of a User to "Active".

1 mandatory parameter is used:

Example: curl "https://www.safedns.com/provider_api/activate?key=PUBLIC_KEY&ident=ACCOUNT_NAME"

Response is returned in JSON format:

{
	"response": {
		"status": "ok"
	}
}

4. deactivate

Sets status of a User to "Inactive".

1 mandatory parameter is used:

Example: curl "https://www.safedns.com/provider_api/deactivate?key=PUBLIC_KEY&ident=ACCOUNT_NAME"

Response is returned in JSON format:

{
	"response": {
		"status": "ok"
	}
}

5. update_email

Updates User’s email.

2 mandatory parameters are used:

Error will be returned, if the user with the same email will be found.

Example: curl "https://www.safedns.com/provider_api/update_email?key=PUBLIC_KEY&ident=ACCOUNT_NAME&email=email@example.com"

Response is returned in JSON format:

{
	"response": {
		"status": "ok"
	}
}

6. update_password

Updates User’s password.

2 mandatory parameters are used:

Example: curl "https://www.safedns.com/provider_api/update_password?key=PUBLIC_KEY&ident=ACCOUNT_NAME&password=StrongPassword123"

Response is returned in JSON format:

{
	"response": {
		"status": "ok"
	}
}

7. prolongate

Enables and changes a paid plan for an existing User.

1 mandatory parameter is used:

1 optional parameter can be used:

Example: curl "https://www.safedns.com/provider_api/prolongate?key=PUBLIC_KEY&ident=ACCOUNT_NAME&plan=ENTERPRISE"

Response is returned in JSON format:

{
	"response": {
		"status": "ok"
	}
}

8. unsubscribe

Switches a User to the FREE plan with the limited filtering functionality.

1 mandatory parameter is used:

Example: curl "https://www.safedns.com/provider_api/unsubscribe?key=PUBLIC_KEY&ident=ACCOUNT_NAME"

Response is returned in JSON format:

{
	"response": {
		"status": "ok"
	}
}

9. subscription_info

Gets the expiration date of the account.

1 mandatory parameter is used:

Example: curl "https://www.safedns.com/provider_api/subscription_info?key=PUBLIC_KEY&ident=ACCOUNT_NAME"

Response is returned in JSON format:

{
	"response": {
		"status": "ok",
		"data": {
			"date_end": 1390930655
		}
	}
}

Expiration date is in UNIX time format.

10. profiles

Gets a list of existing filtering policies.

1 mandatory parameter is used:

Example: curl "https://www.safedns.com/provider_api/profiles?key=PUBLIC_KEY&ident=ACCOUNT_NAME"

Response is returned in JSON format:

{
	"response": {
		"status": "ok",
		"data": {
			"policy ID 1": "policy name",
          	"policy ID 2": "policy name",
          	"policy ID N": "policy name"
		}
	}
}

“Policy name” is returned in UTF-8 encoding.

11. create_profile

Creates a filtering policy.

2 mandatory parameters are used:

1 optional parameter can be used:

Example: curl "https://www.safedns.com/provider_api/create_profile?key=PUBLIC_KEY&ident=ACCOUNT_NAME&name=POLICY_NAME&blockpage_id=ID"

Response is returned in JSON format:

{
	"response": {
		"id": ID number
		"name": profile name
		"status": "ok"
	}
}

12. update_profile

Changes the settings of the User's filtering policy.

1 mandatory parameter is used:

1 optional parameter can be used:

Example: curl "https://www.safedns.com/provider_api/update_profile?key=PUBLIC_KEY&profile_id=POLICY_ID&name=POLICY_NAME"

Response is returned in JSON format:

{
	"response": {
		"status": "ok",
		"data": {
			"id": "profile_id",
          	"name": "profile_name",
          	"tls": "True|False"
		}
	}
}

13. delete_profile

Deletes one of the existing filtering policies.

1 mandatory parameter is used:

1 optional parameter can be used:

Example: curl "https://www.safedns.com/provider_api/method_name?key=PUBLIC_KEY&mandatory_parameter=VALUE&optional_parameter=VALUE"

Response is returned in JSON format:

{
	"response": {
		"status": "ok",
		"result": 0
      	{
		"jsonrpc": "1.9"
		}
	}
}

14. add_ip

Adds one or more IP-address to a User.

2 mandatory parameters are used:

2 optional parameters can be used:

Example: curl "https://www.safedns.com/provider_api/add_ip?key=PUBLIC_KEY&ident=ACCOUNT_NAME&ip=IP_ADDRESS_1&ip=IP_ADDRESS_2&profile=POLICY_ID&comment=COMMENT EXAMPLE"

Response is returned in JSON format:

{
	"response": {
		"status": "ok",
		"data": {
			"added_addresses": ["1.1.1.1", "1.1.1.2"],
			"invalid_adresses": [
				{"1.invalid.ip.adress": "IP address is invalid"},
				{"0.0.0.0": "This address is not public"}
			]
        }
    }
}

If one or multiple IP addresses are invalid, the list of these IP addresses will be returned.

15. clear_ip

Deletes all IP addresses of a User that use selected filtering policy.

2 mandatory parameters are used:

Example: curl "https://www.safedns.com/provider_api/clear_ip?key=PUBLIC_KEY&ident=ACCOUNT_NAME&profile=POLICY_ID"

Response is returned in JSON format:

{
	"response": {
		"status": "ok"
	}
}

16. list_ip

Gets a list of all User’s IP addresses.

1 mandatory parameter is used:

1 optional parameter can be used:

Example: curl "https://www.safedns.com/provider_api/list_ip?key=PUBLIC_KEY&ident=ACCOUNT_NAME&profile=POLICY_ID"

Response is returned in JSON format:

{
	"response": {
		"status": "ok",
		"data": {
			"ip": [
				{"address": "1.2.3.4", "comment": "example.com"},
				{"address": "1.2.3.5", "comment": "example.com"}
			],
		}
	}
}

17. remove_ip

Removes specified IP address from User.

2 mandatory parameters are used:

Example: curl "https://www.safedns.com/provider_api/remove_ip?key=PUBLIC_KEY&ident=ACCOUNT_NAME&ip=IP_ADDRESS"

Response is returned in JSON format:

{
	"response": {
		"status": "ok"
	}
}

18. add_vpn

Creates a VPN Configuration File for the policy and returns OpenVPN policy.

3 mandatory parameters are used:

Example: curl "https://www.safedns.com/provider_api/add_vpn?key=PUBLIC_KEY&ident=ACCOUNT_NAME&name=CONNECTION_NAME&profile_id=POLICY_ID"

Response is returned in JSON format:

{
	"response": {
		"status": "ok",
		"data": {
          "ovpn": "client\nremote vpn.safedns.com 1194 udp\nnobind\ndevtun\npersist-tun\npersist-key\nverify-x509-name vpn.safedns.com name\nremote-cert-tls server\ncipher AES-128-CBC\n\n<ca>\n-----BEGIN CERTIFICATE-----\n ----- ENDCERTIFICATE-----\n-----BEGIN CERTIFICATE-----\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\n-----END CERTIFICATE-----\n</ca>\n<cert>\n----- BEGIN CERTIFICATE-----\n-----END CERTIFICATE-----\n</cert>\n<key>\n-----BEGIN PRIVATE KEY-----\n-----END PRIVATE KEY ---- \n</key>\n"
		}
	}
}

If the limit of VPN connections for an account is exceeded, "Limit is reached" message will be shown.

19. clear_vpn_for_profile

Deletes all VPN Configuration Files that use specified filtering policy.

1 mandatory parameter is used:

Example: curl "https://www.safedns.com/provider_api/clear_vpn_for_profile?key=PUBLIC_KEY&profile_id=POLICY_ID"

Response is returned in JSON format:

{
	"response": {
		"status": "ok"
	}
}

20. clear_vpn_for_user

Deletes all VPN Configuration Files of specified User.

1 mandatory parameter is used:

Example: curl "https://www.safedns.com/provider_api/clear_vpn_for_user?key=PUBLIC_KEY&ident=ACCOUNT_NAME"

Response is returned in JSON format:

{
	"response": {
		"status": "ok"
	}
}

21. get_vpn_list

Gets a list of User’s VPN Configuration Files.

1 mandatory parameter is used:

Example: curl "https://www.safedns.com/provider_api/get_vpn_list?key=PUBLIC_KEY&ident=ACCOUNT_NAME"

Response is returned in JSON format:

{
	"response": {
		"status": "ok",
		"data": [
			{"id": "vpn_id1", "profile": "profile_name", "ip": "vpn_hostname1", "name": "vpn_name1"},
			{"id": "vpn_id2", "profile": "profile_name", "ip": "vpn_hostname2", "name": "vpn_name2"}
		]
	}
}

22. remove_vpn

Removes User’s VPN Configuration File.

1 mandatory parameter is used:

Example: curl "https://www.safedns.com/provider_api/remove_vpn?key=PUBLIC_KEY&id=VPN_ID"

Response is returned in JSON format:

{
	"response": {
		"status": "ok"
	}
}

23. update_ip

Creates a ddclient record and/or updates IP address for it.

2 mandatory parameters are used:

2 optional parameters can be used:

Example: curl "https://www.safedns.com/provider_api/update_ip?key=PUBLIC_KEY&ident=ACCOUNT_NAME&ip=IP_ADDRESS&hostname=John Doe&profile=POLICY_ID"

Response is returned in JSON format:

{
	"response": {
		"status": "ok"
	}
}

24. update_nat

Updates a filtering policy of the specified NAT DNS address.

2 mandatory parameters are used:

Example: curl "https://www.safedns.com/provider_api/update_nat?key=PUBLIC_KEY&profile_id=POLICY_ID&address=NAT_DNS_IP"

Response is returned in JSON format:

{
	"response": {
		"status": "ok"
	}
}

25. get_activity

Gets User’s stats for a certain date.

1 mandatory parameter is used:

2 optional parameters are used:

If no optional parameter is used, a report will be formed for the current date and of all policies.

Example: curl "https://www.safedns.com/provider_api/get_activity?key=PUBLIC_KEY&ident=ACCOUNT_NAME&date=YYYY-MM-DD&profile_id=POLICY_ID"

Response is returned in JSON format:

{
	"response": {
		"status": "ok",
		"data": {
			"requests": "2600",
			"blocks": "581"
		}
	}
}

Where requests is a total number of requests for a given date, and blocks is a number of blocks out of total requests.

26. get_activity_report

Gets User's activity report for the certain time range.

3 mandatory parameters are used:

1 optional parameter is used:

If the range start - end is more than 30 days, then only last 30 days will be included in the report.

Example: curl "https://www.safedns.com/provider_api/get_activity_report?key=PUBLIC_KEY&ident=ACCOUNT_NAME&start=YYYY-MM-DD&end=YYYY-MM-DD&profile_id=POLICY_ID"

Response is returned in JSON format:

{
	"response": {
		"status": "ok",
		"data": {
			"labels": [
				"2016-06-29 14:00:00",
				"2016-06-29 15:00:00"
			],
			"datasets": [
				{
					"label": "Requests",
					"data": [375, 275]
				},
				{
					"label": "Blocks",
					"data": [13, 0]
              }
			]
		}
	}
}

labels - a list of values for the timestamp.
datasets - a list of dictionaries containing datasets of a specific report parameters:
label - name of a report parameter,
data - a list of parameters corresponding to dates from labels list.

27. get_popular_report

Gets User's popular requests report for the certain time range.

3 mandatory parameters are used:

1 optional parameter is used:

If the range start - end is more than 30 days, then only last 30 days will be included in the report.

Example: curl "https://www.safedns.com/provider_api/get_popular_report?key=PUBLIC_KEY&ident=ACCOUNT_NAME&start=YYYY-MM-DD&end=YYYY-MM-DD&profile_id=POLICY_ID"

Response is returned in JSON format:

{
	"response": {
		"status": "ok",
		"data": {
			"labels": [
				"example.com",
            	"google.com",
            	"asdfg.com"
			],
			"datasets": [
				{
					"label": "Requests",
					"data": [630, 474, 290]
				},
				{
					"label": "NXdomain",
					"data": [0, 0, 290]
				},
				{
					"label":"Blocks",
					"data":[630, 0, 0]
				}
			]
		}
	}
}

labels - a list of values for the timestamp.
datasets - a list of dictionaries containing datasets of a specific report parameters:
label - name of a report parameter,
data - a list of parameters corresponding to dates from labels list.

28. get_category_report

Gets User's categories report for the certain time range.

3 mandatory parameters are used:

1 optional parameter is used:

If the range start - end is more than 30 days, then only last 30 days will be included in the report.

Example: curl "https://www.safedns.com/provider_api/get_category_report?key=PUBLIC_KEY&ident=ACCOUNT_NAME&start=YYYY-MM-DD&end=YYYY-MM-DD&profile_id=POLICY_ID"

Response is returned in JSON format:

{
	"response": {
		"status": "ok",
		"data": {
			"Movies & Video": "5",
			"File Storage": "2",
			"Home & Family": "3"
		}
	}
}

data is a dictionary:
key - category name.
value - number of visits.

29. send_monthly_stat

Sends Monthly Stats report to User’s email.

3 mandatory parameters are used:

User must have an email address attached to the account.

1 optional parameter can be used:

User will receive a report in CSV format with stats for the specified month to their email.
Report has the following columns: “Timestamp”, “Domain name”, “Visits”, “Blocks”, “Profile”, “Categories”.

Example: curl "https://www.safedns.com/provider_api/send_monthly_stat?key=PUBLIC_KEY&ident=ACCOUNT_NAME&year=YYYY&month=MM&profile_id=POLICY_ID"

Response is returned in JSON format:

{
	"response": {
		"status": "ok"
	}
}

30. get_daily_stat

Gets a link to User's Daily Stats report.

2 mandatory parameter are used:

2 optional parameters can be used:

Example: curl "https://www.safedns.com/provider_api/get_daily_stat?key=PUBLIC_KEY&date=YYYY-MM-DD&ident=ACCOUNT_NAME&email_to=EMAIL&profile_id=POLICY_ID"

Response is returned in JSON format:

{
	"response": {
		"status": "ok",
		"data": {
			"result": "link for download"
		}
	}
}

31. update_subscription

Changes the billing plan and/or expiration date of Users.

3 optional parameters can be used:

If none parameters are used, users will not be updated.

Examples:

A specified User is updated with a billing plan and gets the expiration date.
curl "https://www.safedns.com/provider_api/update_subscription?key=PUBLIC_KEY&ident=ACCOUNT_NAME&plan=BILLING_PLAN&date=YYYY-MM-DD"

A specified User is updated with a billing plan.
curl "https://www.safedns.com/provider_api/update_subscription?key=PUBLIC_KEY&ident=ACCOUNT_NAME&plan=BILLING_PLAN"

A specified User gets the expiration date.
curl "https://www.safedns.com/provider_api/update_subscription?key=PUBLIC_KEY&ident=ACCOUNT_NAME&date=YYYY-MM-DD"

All Users are updated with a billing plan and get the expiration date.
curl "https://www.safedns.com/provider_api/update_subscription?key=PUBLIC_KEY&plan=BILLING_PLAN&date=YYYY-MM-DD"

All Users are updated with a billing plan.
​curl "https://www.safedns.com/provider_api/update_subscription?key=PUBLIC_KEY&plan=BILLING_PLAN"

All Users get the expiration date.
curl "https://www.safedns.com/provider_api/update_subscription?key=PUBLIC_KEY&date=YYYY-MM-DD"

Response is returned in JSON format:

{
	"response": {
		"status": "ok",
		"result": 0
      	{
		"jsonrpc": "1.9"
		}
	}
}

32. forgot_password

Sends a password reset email to a User.

1 mandatory parameter is be used:

Example: curl "https://www.safedns.com/provider_api/forgot_password?key=PUBLIC_KEY&ident=ACCOUNT_NAME"

Response is returned in JSON format:

{
	"response": {
		"status": "ok",
		"result": 0
      	{
		"jsonrpc": "1.9"
		}
	}
}

If User does not have an email attached to the account, error message "Email not set" will be shown.

---

33. get_blockpages

Gets the list of existing BlockPages.

1 mandatory parameter is be used:

Example: curl "https://www.safedns.com/provider_api/get_blockpages?key=PUBLIC_KEY&ident=ACCOUNT_NAME"

Response is returned in JSON format:

{
	"response": {
		"status": "ok",
		"data": {
			"name": "blockpage 1 name",
          	"id": "blockpage 1 id",
          	"profiles": ["filtering policy id 1 that uses blockpage 1", "policy id 2 that uses blockpage 1"],
          	"type": "blockpage 1 type"
		}
	}
}