ATOM - Secure Platform
Web Service API & SDK Integration Guide
Introduction
What you should know ?
If you're involved with integration, you have to be well-versed with application program interfaces (APIs), which are tools that make it possible to manage software applications. While invisible to end users, APIs are essential for communication between programs. Basically, an open API is one in which an organization publishes its software to be shared freely. A startup, for Sample Response, may want to open its API, as doing so encourages third parties to use its software services.
This guide brings together an integration with Atom Platform using its RESTful APIs as well as explains Atom SDKs available for various Platforms.
About the API
The Atom Platform Web Service API is an Application Programming Interface, which allows you to connect your application with the Atom Platform. Using the Web Service API, you can seamlessly connect with Atom VPN Network in your application.
The Atom Platform Web Service API is a RESTful web service. Some of the advantages of offering integration using a web service include:
1. Platform Independence
Any application that can send and receive RESTful messages can communicate with the Web Service API. Because the Web Service API is built using open standards, you can choose any technology that suits your needs (e.g. J2EE, .NET, PHP, ASP, etc.) for integrating with the Atom Platform.
2. Ease of Integration
The application builds a RESTful request message which encodes your connection request, sends it via HTTPS to the web service, and waits for a RESTful response message. The response contains your connection request’s status. Since RESTful and HTTPS are designed to be lightweight protocols, building requests and parsing responses is a straightforward. Furthermore, rarely do you have to do this manually, since there are a number of libraries available in various technologies. Building a RESTful request and handling the response is reduced to a few lines of code.
NOTE: Integrators of the Atom Platform’s Web Service API should have a working knowledge of Web Service, RESTful and JSON; in addition to a full understanding of how to integrate data into an application or website. All supporting software needed to support Web Service API should be installed in a development environment prior to Web Service implementation. The Integrator must be proficient in their selected programming language.
3. Security
All communication between your application and Atom Platform Web Service API is SSL-encrypted. Your application has a client certificate, which identifies it uniquely with the web service. The Web Service API holds a server certificate, which your application checks to ensure that it is communicating with the Web Service API. These security mechanisms guarantee that the connection request data sent to Atom Platform Web Service API stays private and is available only to your application.
This document will assist you in integrating your application with the Web Service API, and provide a brief summary of the Web Service API solution feature set.
How the Web Service API Works
The following section describes the process of establishing a VPN Connection through the Web Service API.
In most cases, a user starts the overall communication process by dialing to a server with credentials using a network protocol. Though to get the DNS of a VPN Server there are prerequisites explained below:
- Get your Secret Key from Partner’s Console
- Get Access Token via Secret key received in First Step
- Get Fastest Server DNS using GetServer API
- Dial DNS using selected Protocol to establish a Connection
NOTE: The API Secret Key can be retrieved from Partner’s console. Though a prior Sign up and Paid Subscription to the services are also a prerequisite.
Your App sends a VPN Connection Request to the Atom Platform provided DNS with VPN Credentials using the Web Service API. Atom Platform verifies the Credentials and creates a VPN Tunnel over the requested Protocol.
NOTE: Before establishing a VPN Connection you must create a VPN Account. On Account Creation the API will respond with Valid Credentials those are to be use in every VPN Connection Request.
Web service interfaces are designed using the Open API Specification / Swagger. You must have API Secret Key to access these API. As your app requests a connection with valid credentials, connection establishes without prompting you for any other input. A secure connection is established and all data transferred between your application and Internet stay safe from any logging or monitoring by the ISP.
NOTE: All API are called by sending a RESTful request to the following URL: https://api.atom.purevpn.com
This operation returns an JSON-encoded response. Depending on the tools you use to integrate with the Web Service API, you may need to save the API Secret Key in a safe place. If so, you must tell your tool that the communication is SSL-enabled. The process for this depends upon your tool. Consult the documentation for your tool for details. The following section will guide you in setting up your account for building and performing custom VPN Connections.
Getting Started
To begin with you’ll be needing a Subscribed Partner's account that will allow you to access Atom Platform API.
1. Get Access Token
An access token is an opaque string that identifies a user and can be used by the app to make API calls. The token includes information about when the token will expire. Because of privacy checks, the majority of API calls need to include an access token.
Access token can be fetched via Secret Key explained below.
- First, browse to https://www.secure.com/atom/ and login to the platform’s console with your credentials
- Go to the section Secret Key
- Copy the Secret key shared on Screen. (Do not share it with any untrusted source).
After getting the Secret Key, create a REST request to retrieve your access token.
2. Create VPN Account
Each VPN Account has its own credentials (username and password) on Platform, and VPN Services only recognize the credentials associated with the platform. Following are the possibilities to authenticate users with Platform VPN Services
- Platform Provided Credentials
- Create VPN Account via API.
- Above step would return a username and password for the created VPN Account
- Partner is requested to use these credentials to create a VPN Tunnel.
- Single Sign On
Partners looking to authenticate and authorize their existing users (associated with partner’s application), can follow below steps for authenticating and authorizing their users on Platform.
- Create VPN Account via API.
- Above step would return a username and password for the created VPN Account.
- Partner is requested to map these credentials against the email address / username their application is using for authenticating users.
- As user attempts to create a VPN Tunnel, mapped credentials (provided by platform) is to be used with the request.
3. Get Fastest Server
To connect to the fastest server there is an API exposed at an endpoint called GetServer, also an equivalent method encapsulated in Client side SDK.
There are two mechanisms available to get the fastest server from speed test.
-
Ping Datacenter Algorithm (Speed test 4.0 - Recommended)
Ping algorithm is best suited for SDK implementation as SDK offers a PingDataCenters() (explained separately in SDK documentation) to get closest data centers to ensure least latency. This method is to be called with regular intervals to ensure list of best possible data centers.
Note: To get a list of Data Centers you are subscribed to use exposed API.
As user requests for VPN Connection, the closest data centers gets passed to Speed Test Algo, to identify a best VPN server within those Data Centers. -
Via Latitude & Longitude Algorithm (Speed Test 2.0)
This mechanism is to be used when attempting to get the best Server via RESTful API. This method gets the Fastest Server based on your provided Latitude and Longitude and attempts to get the fastest server based on your location
4. Establish VPN Connection
Once fastest Server gets received, you are now ready to attempt to create a VPN Tunnel with the VPN Server returned via Speed Test API. To establish a VPN connection, following Protocols are supported over VPN Servers to create a Tunnel.
- PPTP
- L2TP
- IPSec
- IKEV2
- OpenVPN
Web Service API Reference Manual
API Access Authentication
API in this section are related to API Access and Authentication
-
Get Access Token
URL: <base url>/auth/v1/accessToken
Get Access Token via a Valid Secret Key. The API returns a valid Access Token and a Refresh Token that will expire in 60 minutes. To get a new access token after 60 minutes call the same API with a valid Refresh Token.
Returns JSON object that contains the reseller inventory based on provided Reseller ID
Parameters
Key Type Desc secretKey String Secret Key provided in Reseller Dashboard/Console. Mandatory if “grantType” is “secret” refreshToken String Refresh Token provided in the previous call of “accessToken” made with grant type “secret” having “secretKey” parameter. Mandatory if “grantType” is “refresh” grantType String This identify that accessToken will be grant via which medium Possible mediums are: secret | refresh Returns
Key Type Desc header JSON JSON object that describes return code and message. body JSON JSON object that return access token , refresh token, expiry (in seconds) and reseller id. accessToken String This will use in header (X-AccessToken) for authentication of API’s. refreshToken String This will use in next accessToken call with this refreshToken and grantType “refresh”. expiry int This is the number of seconds for which accessToken is valid for. resellerId int This is the ID of the reseller account. SAMPLE RESPONSE
{ "header": { "code": xxxx, "message": "Success or Fail Message" }, "body": { "accessToken": "xxxxxxxx", "refreshToken": "xxxxxxxx", "expiry": xxxxxxxx, "resellerId": "xxxxxxxx" } }
Inventory Management
-
Get List of All Subscribed Services
URL: <base url>/inventory/v1/getResellerInventory
Use this API to get a complete list of subscribed services.
Returns JSON object that contains the reseller inventory based on provided Reseller ID.
Parameters
Key Type Desc X-AccessToken String Access token required to verify the consumer identity and permissions iId Integer Id of Reseller to get inventory for Returns
Key Type Desc header JSON JSON object that describes return code and message oShared JSON JSON object that contains nested Shared inventory attributes oDedicated String JSON object that contains nested Dedicated inventory attributes oDedicatedNetwork String JSON object that contains nested DedicatedNetwork inventory attributes SAMPLE RESPONSE
{ "header": { "code": 1, "message": "Success" }, "body": { "oShared": { "oIp": {}, "oAccount": {}, "oMultiLogin": {}, "oSessionLimit": {}, "oCountries": {}, "oCities": {}, "oProtocols": {}, "oConcurrentUsers": {}, "oServers": {}, "oAntiVirus": {}, "oAntiPhishing": {}, "oAntiMalware": {}, "oAdBlocker": {}, "oUrlFiltering": {}, "oAppFiltering": {}, "oIds": {}, "oNatfirewall": {} }, "oDedicated": {}, "oDedicatedNetwork": {} } } -
Get Subscribed Protocols
URL: <base url>/inventory/v1/getProtocols
Use this API to get a complete list of subscribed Protocols.
Returns JSON object that contains protocol details
Parameters
Key Type Desc X-AccessToken String Access token required to verify the consumer identity and permissions iResellerId Integer Id of Reseller to get inventory for sDeviceType String (optional) Device type, if need filtered protocols by device type Returns
Key Type Desc header JSON JSON object that describes return code and message protocol JSON JSON object that contains id and name of the protocol SAMPLE RESPONSE
{ "header": { "code": 1, "message": "success" }, "body": { "protocol": [{ "id": 1, "name": "Protocol Name", "number": 10 }, { "id": 2, "name": "Protocol Name", "number": 20 }] } } -
Get Subscribed Cities
URL: <base url>/inventory/v1/getCities
Use this API to get a complete list of subscribed Cities
Returns JSON object that contains the Cities and Datacenters
Parameters
Key Type Desc X-AccessToken String Access token required to verify the consumer identity and permissions iResellerId Integer Id of Reseller to get Cities for Returns
Key Type Desc header JSON JSON object that describes return code and message city Array Array that contains City details and data centers SAMPLE RESPONSE
{ "header": { "code": 1, "message": "success" }, "body": { "city": [{ "id": 1, "name": "City Name", "country_id": 25, Web Service API Integration Guide 15 of 56 "data_centers": [{ "id": 17, "name": "Sample Data Center Name", "ping_ip_address": "127.0.0.1", "host_name": "dc-url.datacenter.com" }, { "id": 154, "name": "Sample Data Center Name", "ping_ip_address": "127.0.0.1", "host_name": "dc-url.datacenter.com" }] }] } } -
Get Subscribed Regions
URL: <base url>/inventory/v1/getRegions
Use this API to get a complete list of subscribed Regions.
Returns JSON object that contains the Regions and Countries
Parameters
Key Type Desc X-AccessToken String Access token required to verify the consumer identity and permissions iResellerId Integer Id of Reseller to get Regions for Returns
Key Type Desc header JSON JSON object that describes return code and message region Array Array that contains region details and countries SAMPLE RESPONSE
{ "header": { "code": 1, "message": "success" }, "body": { "region": [{ "id": 1, "name": "Region Name", "latitude": 1.1245, "longitude":100.656, "countries": [ { "id": 50, "name": "Country Name", "iso_code": "CC", "latitude": 3.375321, "longitude": 96.345116, "background_img_url": "" }, { "id": 19, "name": "Country Name", "iso_code": "PG", "latitude": 6.314993, "longitude": 14.555, "background_img_url": "" }] }] } } -
Get Subscribed Countries
URL: <base url>/inventory/v1/getCountries
Use this API to get a complete list of subscribed Countries
Returns JSON object that contains the Countries and Datacenters
Parameters
Key Type Desc X-AccessToken String Access token required to verify the consumer identity and permissions iResellerId Integer Id of Reseller to get Countries for Returns
Key Type Desc header JSON JSON object that describes return code and message countries Array Array that contains Country details and data centers SAMPLE RESPONSE
{ "header": { "code": 1, "message": "success" }, "body": { "countries": [{ "id": 5, "name": "Country Name", "iso_code": "CC", "latitude": 397.09024, "longitude": 95.712891, "data_centers": [{ "id": 17, "name": "Data Center Name", Web Service API Integration Guide 18 of 56 "ping_ip_address": "127.0.0.1", "host_name": "dc-url-datacenter.com" } ]} ]} } } -
Get Subscribed DataCenters
URL: <base url>/inventory/v1/getDataCenters
Use this API to get a complete list of subscribed Regions.
Returns JSON object that contains the Datacenters
Parameters
Key Type Desc X-AccessToken String Access token required to verify the consumer identity and permissions iResellerId Integer Id of Reseller to get Regions for Returns
Key Type Desc header JSON JSON object that describes return code and message country Array Array that contains Country data, cities, data centers and protocols SAMPLE RESPONSE
{ "header": { "code": 1, "message": "success" }, "body": { "country": [{ "id": 10, "name": "Country Name", "cities": [{ "id": 7344, "name": "City Name", "data_centers": [{ "id": 17, "name": "Data center name", "host_name": "dc-url-datacenter.com", "ping_ip_address": "127.0.0.1", "protocols": [{ "id": 1, "name": "Protocol 1", "number": 1 }, { "id": 8, "name": "Protocol 2", "number": 2 }, { "id": 9, "name": "Protocol 3", "number": 5 }, { "id": 10, "name": "Protocol 4", "number":23 }, { "id": 2, "name": "Protocol 5", "number": 18 }, { "id": 3, "name": "Protocol 6", "number": 19 }] }] }] }] } } -
Get Subscribed Protocols mapping with Cities
URL: <base url>/inventory/v1/getCityProtocols
Use this API to get a complete list of subscribed Protocols mapped with Subscribed Cities.
Returns JSON object that contains Protocols with respect to Cities.
Parameters
Key Type Desc X-AccessToken String Access token required to verify the consumer identity and permissions iResellerId Integer Id of Reseller to get City’s Protocols Returns
Key Type Desc header JSON JSON object that describes return code and message city Array Array that contains list of cities, inside each city; there is an array of offered protocols SAMPLE RESPONSE
{ "header": { "code": 1, "message": "success" }, "body": { "city": [{ "id": 7344, "name": "LosAngeles", "country_id": 254, "protocol": [{ "id": 1, "name": "PPTP", "number": 1 },{ "id": 8, "name": "L2TP", "number": 2 },{ "id": 9, "name": "SSTP", "number": 79617 },{ "id": 10, "name": "IKEV", "number": 3 },{ "id": 2, "name": "TCP", "number": 8 },{ "id": 3, "name": "UDP", "number": 9 },{ "id": 12, "name": "StealthVPN", "number": 10 },{ "id": 13, "name": "IPSEC", "number": 12 }] } ]} } -
Get Subscribed Protocols mapping with Countries
URL: <base url>/inventory/v1/getCountryProtocols
Use this API to get a complete list of subscribed Protocols mapped with Subscribed Countries.
Returns JSON object that contains Protocols with respect to Countries.
Parameters
Key Type Desc X-AccessToken String Access token required to verify the consumer identity and permissions iResellerId Integer Id of Reseller to get Country’s Protocols Returns
Key Type Desc header JSON JSON object that describes return code and message countries Array Array that contains list of countries, inside each country; there is an array of offered protocols SAMPLE RESPONSE
{ "header": { "code": 1, "message": "success" }, "body": { "countries": [{ "id": 254, "name": "United States", "iso_code": "US", "protocol": [{ "id": 1, "name": "PPTP", "number": 1 },{ "id": 8, "name": "L2TP", "number": 2 },{ "id": 9, "name": "SSTP", "number": 79617 },{ "id": 10, "name": "IKEV", "number": 3 },{ "id": 2, "name": "TCP", "number": 8 },{ "id ": 3, "name": "UDP", "number": 9 },{ "id ": 1 2 , "name": "StealthVPN", "number": 10 },{ "id": 13, "name": "IPSEC", "number": 12 }] }] } } -
Get Subscribed Countries’ Purposes
URL: <base url>/inventory/v1/getCountryPurposes
Use this API to get a complete list of subscribed Purposes mapped with Subscribed Countries.
Returns JSON object that contains Purposes with respect to Countries.
Parameters
Key Type Desc X-AccessToken String Access token required to verify the consumer identity and permissions iResellerId Integer Id of Reseller to get Country’s Purposes Returns
Key Type Desc header JSON JSON object that describes return code and message country_purpose Array Array that contains list of countries and their purposes SAMPLE RESPONSE
{ "header": { "code": 1, "message": "success" }, "body": { "country_purpose": [{ "id": 254, "name": "United States", "iso_code": "US", "purpose": [{ "id": , "name": "Entertainment Channels (Faster Streaming)" },{ "id": 5, "name": "Social Media" },{ "id": 7, "name": "Higher Security and Anonymity" },{ "id": 9, "name": "VoIP" }] }] } } -
Get Subscribed DataCenters
URL: <base url>/inventory/v1/getAllDataCenters
Use this API to get a complete list of subscribed DataCenters mapped with Subscribed Countries.
Returns JSON object that contains list of all Datacenters
Parameters
Key Type Desc X-AccessToken String Access token required to verify the consumer identity and permissions iResellerId Integer Id of Reseller to get all data centers Returns
Key Type Desc header JSON JSON object that describes return code and message data_centers Array Array that contains list of all datacenters SAMPLE RESPONSE
{ "header": { "code": 1, "message": "success" }, "body": { "data_centers": [{ "id": "id", "name": "name of datacenter", "ping_ip_address": "datacenter ip", "host_name": "hostname" } ]} }
VPN Account Management (VAM)
-
Get VPN Account Status
URL: <base url>/vam/v1/status
Use this API to check VPN account status by giving VPN username as mandatory parameter
Returns JSON object that contains the VPN username and password
Parameters
Key Type Desc X-AccessToken String Supply AccessToken in the header for authentication vpnUsername String VPN username to check it’s status like Enable or Disable Returns
Key Type Desc header JSON JSON object that describes return code and message body JSON JSON object that return VPN username and status. SAMPLE RESPONSE
{ "header": { "code": xxxx, "message": "Success or Fail Message" }, "body": { "vpnUsername": "xxxxxxxx", "status": "xxxxxxxx" } } -
Create VPN Account
URL: <base url>/vam/v1/create
Use this API to create VPN account by giving UUID as mandatory parameter.
Returns JSON object that contains the VPN username and password
Parameters
Key Type Desc X-AccessToken String Supply AccessToken in the header for authentication uuid String Universal unique identification can be any string or email or unique word Package Type String Package to be assigned to VPN user (Standard, MOBILE, HIGH-BW) period String Period of account (30, 90, 180, 365) preferences JSON A structured JSON to specify that which stuff like country or any sort addon is allow to the VPN account isDedicated Boolean A boolean (True or False) that VPN account will be dedicated or shared oneLoginScheme Boolean This boolean (True or False) indicate that either you’ll provide username and password or it should be auto-generate. Default is ‘False’ vpnUsername String If oneLoginScheme is true then VPN username is mandatory to provide vpnPassword String If oneLoginScheme is true then VPN password is mandatory to provide preferences key example
{ "preferences": { "21": "2000", "22": "2000", "24": [ "1" ], "26": [ "181" ], "27": [ "7344" ], "28": "on", "36": "on" } }Sample Response
Key Type Desc header JSON JSON object that describes return code and message body JSON JSON object that return username and password. Dedicated IP and dedicated host will also return if account would be dedicated SAMPLE RESPONSE
{ "header": { "code": xxxx, "message": "Success or Fail Message" }, "body": { "vpnUsername": "xxxxxxxx", "vpnPassword": "xxxxxxxx", "dedicatedIp": "xx.xx.xx.xx", "hostName": "xx-xxx-xx-xxxxxxxx.xxx" } } -
Generate VPN Account
URL: <base url>/vam/v1/generate
Use this API to create VPN account by giving UUID as mandatory parameter. Create and generate are similar API. The only difference is “generate API” first check if account exist then it will return old account information rather than creating new account but “create API” will always make new VPN account.
Returns JSON object that contains the VPN username and password.
Parameters
Key Type Desc X-AccessToken String Supply AccessToken in the header for authentication uuid String Universal unique identification can be any string or email or unique word Package Type String Package to be assigned to VPN user (Standard, MOBILE, HIGH-BW) period String Period of account (30, 90, 180, 365) preferences JSON A structured JSON to specify that which stuff like country or any sort addon is allow to the VPN account isDedicated Boolean A boolean (True or False) that VPN account will be dedicated or shared dedicatedCountry String If ‘isDedicated’ is true, this parameter should have country ISO code which indicates that this VPN account will have dedicated IP of X country oneLoginScheme Boolean This boolean (True or False) indicate that either you’ll provide username and password or it should be auto-generate. Default is ‘False’ vpnUsername String If oneLoginScheme is true then VPN username is mandatory to provide vpnPassword String If oneLoginScheme is true then VPN password is mandatory to provide Returns
Key Type Desc header JSON JSON object that describes return code and message body JSON JSON object that return username and password. Dedicated IP and dedicated host will also return if account would be dedicated SAMPLE RESPONSE
{ "header": { "code": xxxx, "message": "Success or Fail Message" }, "body": { "vpnUsername": "xxxxxxxx", "vpnPassword": "xxxxxxxx", "dedicatedIp": "xx.xx.xx.xx", "hostName": "xx-xxx-xx-xxxxxxxx.xxx" } } -
Renew VPN Account
URL: <base url>/vam/v1/renew
Use this API to renew and account period and package with Preferences.
Returns JSON object that contains the vpn user name and renew day
Parameters
Key Type Desc vpnUsername String Vpn account Username period Integer Period of account (30, 90, 180, 365) preferences String JSON of User preferences packageType String Package to be assigned to VPN user (Standard, MOBILE, HIGH-BW) oneLoginScheme String Boolean (If true please provide email in vpnUsername) Returns
Key Type Desc header JSON JSON object that describes return code and message body JSON JSON object that return username and renewdays SAMPLE RESPONSE
{ "header": { "code": xxx, "message": "Success or Fail Message " }, "body": { "vpnUsername": "xxxx", "renewForDays": "xxxx" } } -
Update Preferences of a VPN Account
URL: <base url>/vam/v1/updatePreferences
Use this API to update the preferences of the VPN account like allow antivirus to that VPN account or to revoke malware protection from VPN account.
Returns JSON object that contains the VPN username and password
Parameters
Key Type Desc X-AccessToken String Supply AccessToken in the header for authentication vpnUsername String VPN username to update preferences preferences JSON JSON to update preferences keys Returns
Key Type Desc header JSON JSON object that describes return code and message body JSON JSON object that return VPN username and status SAMPLE RESPONSE
{ "header": { "code": xxxx, "message": "Success or Fail Message" }, "body": { "vpnUsername": "xxxxxxxx" } } -
Delete VPN Account
URL: <base url>/vam/v1/delete
Use this API to delete a VPN Account.
Returns JSON object that contains the delete vpn user name
Parameters
Key Type Desc X-AccessToken String Supply AccessToken in the header for authentication vpnUsername String Vpn account Username Returns
Key Type Desc header JSON JSON object that describes return code and message body JSON JSON object that return username thats deleted SAMPLE RESPONSE
{ "header": { "code": xxxx, "message": "Success or Fail Message " }, "body": { "deletedVpnUsername": "xxxxx" } } -
Enable VPN Account
URL: <base url>/vam/v1/enable
Use this API to enable Vpn user for further use.Returns JSON object that contains the vpn user name and updated status.
Returns JSON object that contains the delete vpn user name
Parameters
Key Type Desc X-AccessToken String Supply AccessToken in the header for authentication vpnUsername String Vpn account Username Returns
Key Type Desc header JSON JSON object that describes return code and message body JSON JSON object that return username and user updated status SAMPLE RESPONSE
{ "header": { "code": xxxx, "message": "Success or Fail Message " }, "body": { "vpnUsername": "xxxxx", "statusUpdated": "xxxxxx" } } -
Disable VPN Account
URL: <base url>/vam/v1/disable
Use this API to disable Vpn user for further use. Returns JSON object that contains the vpn username and updated status.
Returns JSON object that contains the delete vpn user name
Parameters
Key Type Desc X-AccessToken String Supply AccessToken in the header for authentication vpnUsername String Vpn account Username Returns
Key Type Desc header JSON JSON object that describes return code and message body JSON JSON object that return username and user updated status SAMPLE RESPONSE
{ "header": { "code": xxxx, "message": "Success or Fail Message " }, "body": { "vpnUsername": "xxxxx", "statusUpdated": "xxxxxx" } } -
Extend Subscription of a VPN Account
URL: <base url>/vam/v1/extendExpiry
Use this API to extend Vpn user expire for further use. Returns JSON object that contains the vpn username and updated expire date.
Returns JSON object that contains the delete vpn user name
Parameters
Key Type Desc X-AccessToken String Supply AccessToken in the header for authentication vpnUsername String Vpn account Username extensionDate String Extension Date to be provided (DD-MM-YYYY) Returns
Key Type Desc header JSON JSON object that describes return code and message body JSON JSON object that return username and user new expire date SAMPLE RESPONSE
{ "header": { "code": xxxx, "message": "Success or Fail Message " }, "body": { "vpnUsername": "xxxxx", "extendedForDays": "xxxxxx" } } -
Change Password of a VPN Account
URL: <base url>/vam/v1/changePassword
Use this API to change a VPN Account Password.
Returns JSON object that contains the vpn username and updated expire date
Parameters
Key Type Desc X-AccessToken String Supply AccessToken in the header for authentication vpnUsername String Vpn account Username newPassword String New Password confirmNewPassword String Should be equal to Password Returns
Key Type Desc header JSON JSON object that describes return code and message body JSON JSON object that return username and user new expire date SAMPLE RESPONSE
{ "header": { "code": xxxx, "message": "Success or Fail Message " }, "body": { "vpnUsername": "xxxxx" } }
Speed Test - Get Fastest Server
-
Get Fastest Server without Pre-Shared Key
URL: <base url>/speedtest/v1/getServersWithoutPsk
Use this API to get fastest server without any pre-sharedkey.
Returns JSON object with list of servers based on provided parameters.
Parameters
Key Type Required Desc X-AccessToken String True Supply AccessToken in the header for authentication iCountryId Integer True Id of the Destination Country iCityId Integer False Id of the Destination City iResellerId Integer True Id of the Reseller iProtocolNumber1 Integer True Protocol No to be used for connection iProtocolNumber2 Integer False Protocol No to be used for connection (Servers returned are always multiport) iProtocolNumber3 Integer False Protocol No to be used for connection (Servers returned are always multiport) iPurposeId Integer False Id of the Purpose iMcs Integer False 0 for returning free servers and 1 for paid. (0/1) iMultiPort Integer False 0 for getting multiport servers (0/1) sDeviceType String True Type of the device (android|ios|mac|windows) sDataCenters json False Json array of datacenters [123,122] sIp String False Ip address of the user sExtras Json False Json object containing advance features Required on server. Where id is the id of advance feature and key is the slug {"aAdvanceFeatures": [ {"id":"10","key":"antivirus"}, {"id":"11","key":"anti_malware"} ]} sUsername String True Username of the user requesting connection Response Description
Key Type Desc header Object Contains Object describing error code and error messages body Array Object containing servers servers Array array of servers containing keys mentioned below host String Host name of the server to be dialed hub_key String Hub key the password required for connection in case of stealthvpn acknowledgement_server String Host of the acknowledgement server port_number String Port number to be pinged for checking servers availability protocol_no Integer Protocol number Requested destination_country Integer Id of the destination country server_type String Type of server (windows/linux) speedtest_method String Calculation method against which the server is returned. Dc is for Datacenter and LL is for Latitude/Longitude (DC/LL) Error Description
Code Message Description 1001 Invalid Params ! One of the Required Params are not provided. 1002 Invalid Reseller ! Invalid Reseller Id provided 1003 Country Not Found in Reseller's inventory Reseller not allowed connection to the requested country 1004 City Not Found in Reseller's inventory Reseller not allowed connection to the requested city 1005 Protocol Not Found in Reseller's inventory Reseller not allowed connection to the requested protocol 1006 Advance Features Not Found in Reseller's inventory Reseller not allowed connection with requested advance features 1007 Failed to Validate Connection Request ! Some error occured while validating reseller's inventory 1008 Login Limit for user Exceeded ! Allowed logins per day exceeded by user. Renews 24 hrs. 1009 Session Limit for user Exceeded ! Allowed sessions per day exceeded by user.
Renews 24 hrs1010 Unable to generate Token! Some error occured while generating psk 1011 Some thing went wrong, inserting data! Some error occured while generating psk 1031 No Servers Found ! No servers found against the requested params. SAMPLE RESPONSE
{ "header": { "code": 1, "message": "Success" }, "body": { "servers": [{ "host": "fs-23454.server.com", "hub_key": "", "acknowledgement_server": null, "port_number": "", "protocol_no": 2, "destination_country": 254, "server_type": "windows", "speedtest_method": "LL" }, { "host": "fs-234543.test.com", "hub_key": "", "acknowledgement_server": null, "port_number": "", "protocol_no": 1, "destination_country": 254, "server_type": "windows", "speedtest_method": "LL" }, { "host": "lux91451.server.com", "hub_key": "", "acknowledgement_server": null, "port_number": "", "protocol_no": 3, "destination_country": 254, "server_type": "windows", "speedtest_method": "LL" }] } } -
Get Pre-Shared Key
URL: <base url>/speedtest/v1/getPsk
Use this API to receive a Pre-Shared Key
Returns JSON object that contains a Pre-Shared Key
Parameters
Key Type Required Desc X-AccessToken String True Supply AccessToken in the header for authentication iCountryId Integer True Id of the Destination Country iCityId Integer False Id of the Destination City iResellerId Integer True Id of the Destination Country iProtocolNumber1 Integer True Protocol No to be used for connection iProtocolNumber2 Integer False Protocol No to be used for connection (Servers returned are always multiport) iProtocolNumber3 Integer False Protocol No to be used for connection (Servers returned are always multiport) iPurposeId Integer False Id of the Purpose iMcs Integer False 0 for returning free servers and 1 for paid. (0/1) iMultiPort Integer False 0 for getting multiport servers (0/1) sDeviceType String True Type of the device (android|ios|mac|windows) sDataCenters json False Json array of datacenters [123,122] sIp String False Ip address of the user sExtras Json False Json object containing advance features Required on server. Where id is the id of advance feature and key is the slug
{"aAdvanceFeatures": [ {"id":"10","key":"antivirus"}, {"id":"11","key":"anti_malware "}]}sUsername String True Username of the user requesting connection Response Keys
Key Type Desc header Object Contains Object describing error code and error messages body Array Object containing psk psk String Preshared key Required by getServers Method Error Description
Code Message Description 1001 Invalid Params ! One of the Required Params are not provided. 1002 Invalid Reseller ! Invalid Reseller Id provided 1003 Country Not Found in Reseller's inventory Reseller not allowed connection to the requested country 1004 City Not Found in Reseller's inventory Reseller not allowed connection to the requested city 1005 Protocol Not Found in Reseller's inventory Reseller not allowed connection to the requested protocol 1006 Advance Features Not Found in Reseller's inventory Reseller not allowed connection with requested advance features 1007 Failed to Validate Connection Request ! Some error occured while validating reseller's inventory. 1008 Login Limit for user Exceeded ! Allowed logins per day exceeded by user. Renews 24 hrs. 1009 Session Limit for user Exceeded ! Allowed sessions per day exceeded by user.
Renews 24 hrs.1010 Unable to generate Token! Some error occured while generating psk. 1011 Some thing went wrong, inserting data! Some error occured while generating psk. Sample Success Response
{ "header": { "code": 1, "message": "Success" }, "body": { "psk": "4522790282be31c543a7f775f5a27175" } } -
Get Servers with PSK
URL: <base url>/speedtest/v1/getServers
Use this API to get the fastest servers bases on the Parameters settled to get the Pre-Shared Key.
Returns JSON object that contains servers on the basis of Pre Shared key provided.
Parameters
Key Type Required Desc X-AccessToken String True Supply AccessToken in the header for authentication sPsk String True Preshared obtained from getPsk method Returns
Key Type Desc header Object Contains Object describing error code and error messages body Array Array Containing servers information required for connection servers Array Array of servers containing keys mentioned below host String Host name of the server to be dialed hub_key String Hub key the password required for connection in case of stealthvpn acknowledgement_server String Host of the acknowledgement server port_number String Port number to be pinged for checking servers availability protocol_no Integer Protocol number Requested destination_country Integer Id of the destination country server_type String Type of server (windows/linux) speedtest_method String Calculation method against which the server is returned. Dc is for Datacenter and LL is for Latitude/Longitude (DC/LL) Error Description
Code Message Description 1030 Invalid Token ! Pre-shared key (psk) provided is invalid 1031 No Servers Found ! No servers found against the requested params -
Renew VPN Account
URL: <base url>/vam/v1/renew
Use this API to renew and account period and package with Preferences.
Returns JSON object that contains the vpn user name and renew day
Parameters
Key Type Desc vpnUsername String Vpn account Username period Integer Period of account (30, 90, 180, 365) preferences String JSON of User preferences packageType String Package to be assigned to VPN user (Standard, MOBILE, HIGH-BW) oneLoginScheme String Boolean (If true please provide email in vpnUsername) Sample Success Response
{ "header": { "code": 1, "message": "Success" }, "body": { "servers": [{ "host": "fs-23454.server.com", "hub_key": "", "acknowledgement_server": null, "port_number": "", "protocol_no": 2, "destination_country": 254, "server_type": "windows", "speedtest_method": "LL" }, { "host": "fs-234543.test.com", "hub_key": "", "acknowledgement_server": null, "port_number": "", "protocol_no": 1, "destination_country": 254, "server_type": "windows", "speedtest_method": "LL" }, { "host": "lux91451.server.com", "hub_key": "", "acknowledgement_server": null, "port_number": "", "protocol_no": 3, "destination_country": 254, "server_type": "windows", "speedtest_method": "LL" }] } }
Software Development Kit (SDK)
A Software Development Kit is prepared for the following platforms:
Rest of the platforms can integrate with VPN via REST APIs exposed. A complete list of APIs will be exposed on Platform Website with a proper API Playground.
ATOM SDK documentation is separated by our supported platforms. Kindly scroll below to explore the information related to every platform.
Windows SDK Documentation
Compatibility
- Compatible with Microsoft Visual Studio 2015 and onwards
- Minimum .Net Framework 4.5 required
- Compatible with ATOM SDK Version 2.0 and onwards
Supported Protocols
- IKEv2
- L2TP
- PPTP
- SSTP
- TCP
- UDP
SDK Installation
Install the latest version of Atom Windows SDK through NuGet.
Install-Package Atom.SDK.Net -Version 2.0.0
Run Atom.SDK.Installer.exe to install supporting services and drivers on any system. The same Installer should be accompanied with your application setup to get the required files installed on your customer's system.
Atom.SDK.Net.dll.config file should be copied to the output directory where Atom.SDK.Net.dll is present (only if the config file is not already there) since AtomSDK will read the name of your RAS VPN Adapter mentioned in this config against RAS_ADAPTER_NAME key.
Getting Started with the Code
ATOM SDK needs to be initialized with a “SecretKey” provided to you after you buy the subscription which is typically a hex-numeric literal.
var atomManagerInstance = AtomManager.Initialize(“SECRETKEY_GOES_HERE”);
OR
It can be initialized using an instance of AtomConfiguration. It should have a VpnInterfaceName which will be used to create the Network Interface for VPN connection.
var atomConfiguration = new AtomConfiguration(“SECRETKEY_GOES_HERE”);
atomConfiguration.VpnInterfaceName = "Atom";
atomConfiguration.BaseUrl = new Uri("YOUR_BASE_URL"); // Optional
var atomManagerInstance = AtomManager.Initialize(atomConfiguration);
PS: ATOM SDK is a singleton, and must be initialized before accessing its methods, otherwise NullObjectReference Exception will be thrown.
Enable Local Inventory Support
ATOM SDK offers a feature to enable the local inventory support. This can help Application to fetch Countries and Protocols even when device network is not working.
- To enable it, Log In to the Atom Console
- Download the local data file in json format
- File name should be localdata.json. Please rename the file to localdata.json if you find any discrepancy in the file name.
- Paste the file in the output directory of your application
Events to Register
ATOM SDK offers five events to register for the ease of the developer.
- StateChanged
- Connected
- Disconnected
- DialError
- Redialing
Details of these events can be seen in the inline documentation or method summaries. You need to register these events to get notified about what’s happening behind the scenes
atomManagerInstance.Connected += AtomManagerInstance_Connected; atomManagerInstance.DialError += AtomManagerInstance_DialError; atomManagerInstance.Disconnected += AtomManagerInstance_Disconnected; atomManagerInstance.StateChanged += AtomManagerInstance_StateChanged; atomManagerInstance.Redialing += AtomManagerInstance_Redialing;
Events will be registered with the respective EventArgs customized for the ease of the developer.
VPN Authentication
ATOM SDK provided two ways to authenticate your vpn user. First one is to offer VPN Credentials directly to the SDK which you may create through the Admin Panel provided by ATOM.
atomManagerInstance.Credentials = new Credentials("VPNUsername","VPNPassword");
Alternatively, if you don’t want to take hassle of creating users yourself, leave it on us and we will do the rest for you! Easy isn't it.
atomManagerInstance.UUID = “UniqueUserID”;
You just need to provide a Unique User ID for your user e.g. any unique hash or even user’s email which you think remains consistent and unique for your user. ATOM SDK will generate VPN Account behind the scenes automatically and gets your user connected!
VPN Connection
You need to declare an object of “VPNProperties” Class to define your connection preferences. Details of all the available properties can be seen in the inline documentation of “VPNProperties” Class. For the least, you need to give Country and Protocol with which you want to connect.
var vpnProperties = new VPNProperties(Country country, Protocol protocol);
Fetch Countries
You can get the Countries list through ATOM SDK.
var countries = atomManagerInstance.GetCountries();
Fetch Countries For Smart Dialing
You can get the Countries those support Smart Dialing through ATOM SDK.
var countries = AtomManagerInstance.GetCountriesForSmartDialing();
Fetch Protocols
Protocols can be obtained through ATOM SDK as well.
var protocols = atomManagerInstance.GetProtocols();
How to Connect
As soon as you call Connect method, the events you were listening to will get the updates about the states being changed and Dial Error (if any occurs as well).
After initializing the VPNProperties, just call Connect method of ATOM SDK.
Connection with Parameters
It is the simplest way of connection which is well explained in the steps above. You just need to provide the Country and the Protocol objects and call the Connect method.
var vpnProperties = new VPNProperties(Country country, Protocol protocol); atomManagerInstance.Connect(properties);
Connection with Pre-Shared Key (PSK)
In this way of connection, it is pre-assumed that you have your own backend server which communicates with ATOM Backend APIs directly and creates a Pre-Shared Key (usually called as PSK) which you can then provide to the SDK for dialing. While providing PSK, no VPN Property other than PSK is required to make the connection. ATOM SDK will handle the rest.
var vpnProperties = new VPNProperties(string PSK); atomManagerInstance.Connect(properties);
Connection with Dedicated IP
You can also make your user comfortable with this type of connection by just providing them with a Dedicated DNS Host and they will always connect to a dedicated server! For this purpose, ATOM SDK provides you with the following constructor.
var vpnProperties = new VPNProperties(string hostName, Protocol protocol); atomManagerInstance.Connect(properties);
Connection with Real-time Optimized Servers
This one is same as the first one i.e. “Connection with Parameters” with a slight addition of using Real-time optimized servers best from your user’s location. You just need to set this property to TRUE and rest will be handled by the ATOM SDK.
var vpnProperties = new VPNProperties(Country country, Protocol protocol); vpnProperties.UseOptimization= true; atomManagerInstance.Connect(properties);
For more information, please see the inline documentation of VPNProperties Class.
If you want to show your user the best location for him on your GUI then ATOM SDK have it ready for you as well! ATOM SDK has a method exposed namely “GetOptimizedCountries()” which adds a property “Latency” in the country object which has the real-time latency of all countries from your user’s location (only if ping is enabled on your user’s system and ISP doesn’t blocks any of our datacenters). You can use this property to find the best speed countries from your user’s location.
Connection with Smart Dialing
“Connection with Parameters” with a slight addition of using smart dialing to connect. You just need to call "withSmartDialing" and rest will handled by the ATOM SDK.
var vpnProperties = new VPNProperties(Country country, Protocol protocol); vpnProperties.UseSmartDialing= true; atomManagerInstance.Connect(properties);
For more information, please see the inline documentation of VPNProperties Class.
Connection with Multiple Protocols (Auto-Retry Functionality)
You can provide THREE Protocols at max so ATOM SDK can attempt automatically on your behalf to get your user connected with the Secondary or Tertiary protocol if your primary Protocol fails to connect.
vpnProperties.SecondaryProtocol = ProtocolObject; vpnProperties.TertiaryProtocol = ProtocolObject;
For more information, please see the inline documentation of VPNProperties Class.
Cancel VPN Connection
You can cancel connection between dialing process by calling the Cancel method.
atomManagerInstance.Cancel();
Disconnect VPN Connection
To disconnect, simply call the Disconnect method of AtomManager.
atomManagerInstance.Disconnect();
Resolve dependencies conflicts if any :
In case any dependency conflict is faced while building/running ATOM SDK with your application e.g. different version of Newtonsoft.Json used in your application, define the binding redirect in your app configuration like following:
<dependentAssembly>
<assemblyIdentity name="Newtonsoft.Json" publicKeyToken="30ad4fe6b2a6aeed" culture="neutral" />
<bindingRedirect oldVersion="0.0.0.0-11.0.0.0" newVersion="11.0.0.0" />
</dependentAssembly>
where "0.0.0.0-11.0.0.0" is the minimum and maximum version range of Newtonsoft.Json.
MAC SDK Documentation
Compatibility
- Compatible with Xcode 9 and OS X 10.11 and later
- Compatible with ATOM SDK Version 2.0 and onwards
Supported Protocols
- IPSec
SDK Installation
Although ATOM SDK Framework is already provided with the demo application but you can install the latest version through this link
Getting Started with the Code
To add the SDK in Xcode:
- Open your Xcode project.
- Add your developer account to Xcode from Preferences -> Account if you didn't add before.
- Select General tab from your app target and then set your developer account details.
- From your app target select Capabilities tab and select the switch right of the Personal VPN. Then select the capabilties you are going to use.
- Drag and drop AtomSDK.framework into your project.
- Go to your project -> General tab from your app target, add the framework using ‘+’ to the Embedded Binaries section.
- After the setup is completed, you should be able to use all the classes from the SDK by including it with the #import
directive. - ATOM SDK needs to be initialized with a “SecretKey” provided to you after you buy the subscription which is typically a hex-numeric literal.
Using App Secret Key:
Use the following setup code in your AppDelegate's application:didFinishLaunchingWithOptions: method: [AtomManager sharedInstanceWithSecretKey:@"<#Secret Key#>"];
OR
It can be initialized using an instance of AtomConfiguration. It should have a vpnInterfaceName which will be used to create the Network Interface for VPN connection.
AtomConfiguration *atomConfiguration = [[AtomConfiguration alloc] init]; atomConfiguration.secretKey = @"<#SECRETKEY_GOES_HERE#>>"; atomConfiguration.vpnInterfaceName = @"Atom"; [AtomManager sharedInstanceWithAtomConfiguration:atomConfiguration];
PS: ATOM SDK is a singleton, and must be initialized before accessing its methods.
Delegates to Register
ATOM SDK offers four delegates to register for the ease of the developer.
- atomManagerDidConnect
- atomManagerDidDisconnect
- atomManagerDialErrorReceived
- atomManagerOnRedialing
stateDidChangedHandler to monitor a VPN connection status
ATOM SDK offers stateDidChangedHandler for the ease of the developer.
[AtomManager sharedInstance].stateDidChangedHandler = ^(AtomVPNState status){};
VPN Authentication
ATOM SDK provided two ways to authenticate your vpn user. First one is to offer VPN Credentials directly to the SDK which you may create through the Admin Panel provided by ATOM.
[AtomManager sharedInstance].atomCredential = [[AtomCredential alloc] initWithUsername:@"<username>" password:@"<password>"];
Alternatively, if you don’t want to take hassle of creating users yourself, leave it on us and we will do the rest for you!
[AtomManager sharedInstance].UUID = @"<#[[NSUUID UUID] UUIDString]#>";
You just need to provide a Unique User ID for your user e.g. any unique hash or even user’s email which you think remains consistent and unique for your user. ATOM SDK will generate VPN Account behind the scenes automatically and gets your user connected! Easy isn’t it
VPN Connection
You need to declare an object of “AtomProperties” Class to define your connection preferences. Details of all the available properties can be seen in the inline documentation of “AtomProperties” Class. For the least, you need to give Country and Protocol with which you want to connect.
AtomProperties* properties = [[AtomProperties alloc] initWithCountry:@"<#country#>" protocol:@"<#protocol#>"];
Fetch Countries
You can get the Countries list through ATOM SDK.
[[AtomManager sharedInstance] getCountriesWithSuccess:^(NSArray<AtomCountry *> *success) {}
} errorBlock:^(NSError *error) {}];
Fetch Countries For Smart Dialing
You can get the Countries those support Smart Dialing through ATOM SDK.
[[AtomManager sharedInstance] getCountriesForSmartDialing:^(NSArray<AtomCountry *> *success) {}
} errorBlock:^(NSError *error) {}];
Fetch Protocols
Protocols can be obtained through ATOM SDK as well.
[[AtomManager sharedInstance] getProtocolsWithSuccess:^(NSArray<AtomProtocol *> *success) {}
errorBlock:^(NSError *error) {}];
How to Connect
As soon as you call Connect method, the events you were listening to will get the updates about the states being changed and VPNDialedError (if any occurs) as well.
After initializing the VPNProperties, just call Connect method of ATOM SDK.
Connection with Parameters
It is the simplest way of connection which is well explained in the steps above. You just need to provide the Country and the Protocol objects and call the Connect method.
AtomProperties* properties = [[AtomProperties alloc] initWithCountry:@"<#country#>" protocol:@"<#protocol#>"];
[[AtomManager sharedInstance] connectWithProperties:@"<#properties#>" completion:^(NSString *success) {}
errorBlock:^(NSError *error) {}];
Connection with Pre-Shared Key (PSK)
In this way of connection, it is pre-assumed that you have your own backend server which communicates with ATOM Backend APIs directly and creates a Pre-Shared Key (usually called as PSK) which you can then provide to the SDK for dialing. While providing PSK, no VPN Property other than PSK is required to make the connection. ATOM SDK will handle the rest.
AtomProperties *properties = [[AtomProperties alloc] initWithPreSharedKey:@"<#PSK#>"];
[[AtomManager sharedInstance] connectWithProperties:@"<#properties#>" completion:^(NSString *success) {}
errorBlock:^(NSError *error) {}];
Connection with Dedicated IP
You can also make your user comfortable with this type of connection by just providing them with a Dedicated IP/Host and they will always connect to a dedicated server! For this purpose, ATOM SDK provides you with the following constructor.
AtomProperties *properties = [[AtomProperties alloc] initWithDedicatedHostName:@"<#DedicatedIP/Host#>" protocol:@"<#protocol#>"];
[[AtomManager sharedInstance] connectWithProperties:@"<#properties#>" completion:^(NSString *success) {}
errorBlock:^(NSError *error) {}];
Connection with Real-time Optimized Servers
This one is same as the first one i.e. “Connection with Parameters” with a slight addition of using Real-time optimized servers best from your user’s location. You just need to set this property to TRUE and rest will be handled by the ATOM SDK.
AtomProperties* properties = [[AtomProperties alloc] initWithCountry:@"<#country#>" protocol:@"<#protocol#>"];
[properties setUseOptimization:TRUE];
[[AtomManager sharedInstance] connectWithProperties:@"<#properties#>" completion:^(NSString *success) {}
errorBlock:^(NSError *error) {}];
If you want to show your user the best location for him on your GUI then ATOM SDK have it ready for you as well! ATOM SDK has a method exposed namely “getOptimizedCountries” which adds a property “latency” in the country object which has the real-time latency of all countries from your user’s location (only if ping is enabled on your user’s system and ISP doesn’t blocks any of our datacenters). You can use this property to find the best speed countries from your user’s location.
For more information, please see the inline documentation of AtomProperties Class.
Connection with Smart Dialing
“Connection with Parameters” with a slight addition of using smart dialing to connect. You just need to call "withSmartDialing" and rest will handled by the ATOM SDK.
AtomProperties* properties = [[AtomProperties alloc] initWithCountry:@"<#country#>" protocol:@"<#protocol#>"];
[properties setUseSmartDialing:YES];
[[AtomManager sharedInstance] connectWithProperties:properties completion:^(NSString *success) {}
errorBlock:^(NSError *error) {}];
For more information, please see the inline documentation of AtomProperties Class.
Cancel VPN Connection
You can cancel connection between dialing process by calling the cancelVPN method.
[[AtomManager sharedInstance] cancelVPN];
Disconnect VPN Connection
To disconnect, simply call the disconnectVPN method of AtomManager.
[[AtomManager sharedInstance] disconnectVPN];
NOTE: The current version of the VPN Atom SDK uses the following library under the hood:
- NEVPNManager
ANDROID SDK Documentation
Compatibility
- Compatible with Android 4.0/API Level: 14 (ICE_CREAM_SANDWICH) and later
- Compatible with ATOM SDK Version 2.0 and onwards
Supported Protocols
- TCP
- UDP
- IKEV
SDK Installation
Although ATOM SDK library is already compiled with the demo application but you can download the latest version from ATOM SDK Download
Import module aar as library in your project using Android Studio then add it to build.gradle of app
implementation project(':AtomSdk-2.0')
To successfully build ATOM SDK, developer must enable Kotlin support in Android Studio using Kotlin Extension.
Setup Kotlin Extension in Android Studio
Add Kotlin gradle plugin to project build.gradle
classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:1.2.71"
Add Kotlin Android Extension plugin to app build.gradle
apply plugin: 'kotlin-android-extensions' apply plugin: 'kotlin-android'
Add Kotlin support to app build.gradle in dependencies
implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk7:1.2.71"
Getting Started with the Code
ATOM SDK needs to be initialized with a “SecretKey” provided to you after you buy the subscription which is typically a hex-numeric literal.
Don’t forget to change the following entry with your SECRET KEY.
// Put Atom SDK Secret Key here <string name="atom_secret_key"></string>
ATOM SDK should be initialize in Application's onCreate method.
AtomConfiguration.Builder atomConfigurationBuilder = new AtomConfiguration.Builder(getString(R.string.atom_secret_key));
AtomConfiguration atomConfiguration = atomConfigurationBuilder.build();
AtomManager.initialize(this, atomConfiguration, new AtomManager.InitializeCallback() {
@Override
public void onInitialized(AtomManager atomManager) {
// Get initialized AtomManager instance here
}
});
PS: ATOM SDK is a singleton, and must be initialized before accessing its methods, otherwise NullPointerException will be thrown.
Enable Local Inventory Support
ATOM SDK offers a feature to enable the local inventory support. This can help Application to fetch Countries and Protocols even when device network is not working.
- To enable it, Log In to the Atom Console
- Download the local data file in json format
- File name should be localdata.json. Please rename the file to localdata.json if you find any discrepancy in the file name.
- Paste the file in assets folder of your application.
Callbacks to Register
ATOM SDK offers five callbacks to register for the ease of the developer.
- onStateChange
- onConnected
- onDisconnected
- onDialError
- onRedialing
Details of these callbacks can be seen in the inline documentation or method summaries. You need to register these callback to get notified about what’s happening behind the scenes
AtomManager.addVPNStateListener(VPNStateListener this);
Remove the callback using
AtomManager.removeVPNStateListener(VPNStateListener this);
Listening to IKEV Callbacks
While connecting to IKEV protocol callbacks must be registered using bind service
atomManager.bindIKEVStateService(this);
and unbind using
atomManager.unBindIKEVStateService(this);
Callbacks will be registered for the ease of the developer.
@Override
public void onStateChange(String state) {
}
@Override
public void onConnected() {
}
@Override
public void onDisconnected(boolean isCancelled) {
}
@Override
public void onDialError(AtomException exception, ConnectionDetails connectionDetails) {
}
@Override
public void onRedialing(AtomException exception, ConnectionDetails connectionDetails) {
}
Packet Transmitted Callback
ATOM SDK offers an additional callback onPacketTransmitted only trigger while connected using TCP or UDP to read in/out packet transmitted.
@Override
public void onPacketsTransmitted(String in, String out) {
}
VPN Authentication
ATOM SDK provided two ways to authenticate your vpn user. First one is to offer VPN Credentials directly to the SDK which you may create through the Admin Panel provided by ATOM.
AtomManager.getInstance().setVPNCredentials(new VPNCredentials(String VPNUsername,String VPNPassword));
Alternatively, if you don’t want to take hassle of creating users yourself, leave it on us and we will do the rest for you!
AtomManager.getInstance().setUUID(String UniqueUserID);
You just need to provide a Unique User ID for your user e.g. any unique hash or even user’s email which you think remains consistent and unique for your user. ATOM SDK will generate VPN Account behind the scenes automatically and gets your user connected! Easy isn’t it?
VPN Connection
You need to declare an object of “VPNProperties” Class to define your connection preferences. Details of all the available properties can be seen in the inline documentation of “VPNProperties” Class. For the least, you need to give Country and Protocol with which you want to connect.
VPNProperties.Builder vpnPropertiesBuilder = new VPNProperties.Builder(Country country, Protocol protocol); VPNProperties vpnProperties = vpnPropertiesBuilder.build();
Fetch Countries
You can get the Countries list through ATOM SDK.
atomManager.getCountries(new Callback<List<Country>>() {
@Override
public void onSuccess(List<Country> countries) {
}
@Override
public void onError(AtomException exception) {
}
@Override
public void onNetworkError(AtomException exception) {
}
});
Fetch Countries For Smart Dialing
You can get the Countries those support Smart Dialing through ATOM SDK.
atomManager.getCountriesForSmartDialing(new Callback<List<Country>>() {
@Override
public void onSuccess(List<Country> countries) {
}
@Override
public void onError(AtomException exception) {
}
@Override
public void onNetworkError(AtomException exception) {
}
});
Fetch Protocols
Protocols can be obtained through ATOM SDK.
atomManager.getProtocols(new CollectionCallback<Protocol>() {
@Override
public void onSuccess(List<Protocol> protocols) {
}
@Override
public void onError(AtomException exception) {
}
@Override
public void onNetworkError(AtomException exception) {
}
});
How to Connect
As soon as you call Connect method, the callbacks you were listening to will get the updates about the states being changed and Dial Error (if any occurs) as well.
After initializing the VPNProperties, just call Connect method of ATOM SDK.
Connection with Parameters
It is the simplest way of connection which is well explained in the steps above. You just need to provide the Country and the Protocol objects and call the Connect method.
VPNProperties.Builder vpnPropertiesBuilder = new VPNProperties.Builder(Country country, Protocol protocol); VPNProperties vpnProperties = vpnPropertiesBuilder.build(); atomManager.connect(this, vpnProperties);
Connection with Pre-Shared Key (PSK)
In this way of connection, it is pre-assumed that you have your own backend server which communicates with ATOM Backend APIs directly and creates a Pre-Shared Key (usually called as PSK) which you can then provide to the SDK for dialing. While providing PSK, no VPN Property other than PSK is required to make the connection. ATOM SDK will handle the rest.
VPNProperties vpnProperties = new VPNProperties.Builder(String PSK).build(); atomManager.connect(this, vpnProperties);
Connection with Dedicated IP
You can also make your user comfortable with this type of connection by just providing them with a Dedicated DNS Host and they will always connect to a dedicated server! For this purpose, ATOM SDK provides you with the following constructor.
VPNProperties vpnProperties = new VPNProperties.Builder(String dedicatedHostName, Protocol protocol).build(); atomManager.connect(this, vpnProperties);
Connection with Real-time Optimized Servers
This one is same as the first one i.e. “Connection with Parameters” with a slight addition of using Real-time optimized servers best from your user’s location. You just need to call "withOptimization" and rest will be handled by the ATOM SDK.
VPNProperties.Builder vpnPropertiesBuilder = new VPNProperties.Builder(Country country, Protocol protocol).withOptimization(); VPNProperties vpnProperties = vpnPropertiesBuilder.build(); atomManager.connect(this, vpnProperties);
If you want to show your user the best location for him on your GUI then ATOM SDK have it ready for you as well! ATOM SDK has a method exposed namely “getOptimizedCountries” which has a method “getLatency()” in the country object which has the real-time latency of all countries from your user’s location (only if ping is enabled on your user’s system and ISP doesn’t blocks any of our datacenters). You can use this property to find the best speed countries from your user’s location.
Connection with Smart Dialing
“Connection with Parameters” with a slight addition of using smart dialing to connect. You just need to call "withSmartDialing" and rest will handled by the ATOM SDK.
VPNProperties.Builder vpnPropertiesBuilder = new VPNProperties.Builder(Country country, Protocol protocol).withSmartDialing(); VPNProperties vpnProperties = vpnPropertiesBuilder.build(); atomManager.connect(this, vpnProperties);
Connection with Multiple Protocols (Auto-Retry Functionality)
You can provide THREE Protocols at max so ATOM SDK can attempt automatically on your behalf to get your user connected with the Secondary or Tertiary Protocol if your base Protocol fails to connect.
VPNProperties.Builder vpnPropertiesBuilder = new VPNProperties.Builder(Country country, Protocol protocol); vpnPropertiesBuilder.withSecondaryProtocol(Protocol secondaryProtocol); vpnPropertiesBuilder.withTertiaryProtocol(Protocol tertiaryProtocol); VPNProperties vpnProperties = vpnPropertiesBuilder.build(); atomManager.connect(this, vpnProperties);
For more information, please see the inline documentation of VPNProperties Class.
Cancel VPN Connection
You can Cancel connection between dialing process by calling following method.
atomManager.cancel(Context context);
Disconnect VPN Connection
To disconnect, simply call the Disconnect method of AtomManager.
atomManager.disconnect(Context context);
Proguard rules:
-dontwarn com.atom.sdk.**
-keep class com.atom.sdk.** { *; }
-keep interface com.atom.sdk.** { *; }
Resolve dependencies conflicts if any :
In case any dependency conflict is faced while building ATOM SDK with your application e.g. “Duplicate jar entry”, exclude that dependency from app build.gradle configuration.
android{
configurations {
all*.exclude module: 'DEPENDENCY_MODULE_NAME_HERE'
}
}
iOS SDK Documentation
Compatibility
- Compatible with Xcode 9 and iOS 9 and later
- Compatible with ATOM SDK Version 2.0 and onwards
Supported Protocols
- IPSec
- IKEV
SDK Installation
Although ATOM SDK Framework is already provided with the demo application but you can install the latest version through this link
Getting Started with the Code
To add the SDK in Xcode:
- Open your Xcode project.
- Add your developer account to Xcode from Preferences -> Account if you didn't add before.
- Select General tab from your app target and then set your developer account details.
- From your app target select Capabilities tab and select the switch right of the Personal VPN. Then select the capabilties you are going to use.
- Drag and drop AtomSDK.framework into your project.
- Go to your project -> General tab from your app target, add the framework using ‘+’ to the Embedded Binaries section.
- After the setup is completed, you should be able to use all the classes from the SDK by including it with the #import <AtomSDK/AtomSDK.h> directive.
- ATOM SDK needs to be initialized with a “SecretKey” provided to you after you buy the subscription which is typically a hex-numeric literal.
Using App Secret Key
Use the following setup code in your AppDelegate's application:didFinishLaunchingWithOptions: method: [AtomManager sharedInstanceWithSecretKey:@"<#Secret Key#>"];
OR
It can be initialized using an instance of AtomConfiguration. It should have a vpnInterfaceName which will be used to create the Network Interface for VPN connection.
AtomConfiguration *atomConfiguration= [[AtomConfiguration alloc] init];
atomConfig.secretKey = @"SECRETKEY_GOES_HERE";
atomConfig.vpnInterfaceName = @"Atom";
[AtomManager sharedInstanceWithAtomConfiguration:atomConfig];
PS: ATOM SDK is a singleton, and must be initialized before accessing its methods.
Enable Local Inventory Support
ATOM SDK offers a feature to enable the local inventory support. This can help Application to fetch Countries and Protocols even when device network is not working.
- To enable it, Log In to the Atom Console
- Download the local data file in json format
- File name should be localdata.json. Please rename the file to localdata.json if you find any discrepancy in the file name.
- Paste the file in root of your application folder.
Delegates to Register
ATOM SDK offers four delegates to register for the ease of the developer.
- atomManagerDidConnect
- atomManagerDidDisconnect
- atomManagerOnRedialing
- atomManagerDialErrorReceived
StateDidChangedHandler to monitor a VPN connection status
ATOM SDK offers stateDidChangedHandler for the ease of the developer.
[AtomManager sharedInstance].stateDidChangedHandler = ^(AtomVPNState status) { };
VPN Authentication
ATOM SDK provided two ways to authenticate your vpn user. First one is to offer VPN Credentials directly to the SDK which you may create through the Admin Panel provided by ATOM.
[AtomManager sharedInstance].atomCredential = [[AtomCredential alloc] initWithUsername:@"<username>" password:@"<password>"];
Alternatively, if you don’t want to take hassle of creating users yourself, leave it on us and we will do the rest for you!
[AtomManager sharedInstance].UUID = @<"[[[UIDevice currentDevice] identifierForVendor] UUIDString]>";
You just need to provide a Unique User ID for your user e.g. any unique hash or even user’s email which you think remains consistent and unique for your user. ATOM SDK will generate VPN Account behind the scenes automatically and gets your user connected! Easy isn’t it?
VPN Connection
You need to declare an object of “VPNProperties” Class to define your connection preferences. Details of all the available properties can be seen in the inline documentation of “AtomProperties” Class. For the least, you need to give Country and Protocol with which you want to connect.
AtomProperties* properties = [[AtomProperties alloc] initWithCountry:@"<country>" protocol:@"<protocol>"];
Fetch Countries
Countries can be obtained through ATOM SDK as well.
[[AtomManager sharedInstance] getCountriesWithSuccess:^(NSArray<AtomCountry *> *success) {}
} errorBlock:^(NSError *error) {}];
Fetch Countries For Smart Dialing
You can get the Countries those support Smart Dialing through ATOM SDK.
[[AtomManager sharedInstance] getCountriesForSmartDialing:^(NSArray<AtomCountry *> *success) {}
} errorBlock:^(NSError *error) {}];
Fetch Protocols
Protocols can be obtained through ATOM SDK as well.
[[AtomManager sharedInstance] getProtocolsWithSuccess:^(NSArray<AtomProtocol *> *success) {}
errorBlock:^(NSError *error) {}];
How to Connect
As soon as you call Connect method, the events you were listening to will get the updates about the states being changed and VPNDialedError (if any occurs) as well.
Connection with Parameters
It is the simplest way of connection which is well explained in the steps above. You just need to provide the country and the protocol objects and call the Connect method.
AtomProperties* properties = [[AtomProperties alloc] initWithCountry:@"<#country#>" protocol:@"<#protocol#>"];
[[AtomManager sharedInstance] connectWithProperties:properties completion:^(NSString *success) {}
errorBlock:^(NSError *error) {}];
Connection with Pre-Shared Key (PSK)
In this way of connection, it is pre-assumed that you have your own backend server which communicates with ATOM Backend APIs directly and creates a Pre-Shared Key (usually called as PSK) which you can then provide to the SDK for dialing. While providing PSK, no VPN Property other than PSK is required to make the connection. ATOM SDK will handle the rest.
AtomProperties *properties = [[AtomProperties alloc] initWithPreSharedKey:@"<#PSK#>"];
[[AtomManager sharedInstance] connectWithProperties:properties completion:^(NSString *success) {}
errorBlock:^(NSError *error) {}];
Connection with Dedicated IP
You can also make your user comfortable with this type of connection by just providing them with a Dedicated IP/Host and they will always connect to a dedicated server! For this purpose, ATOM SDK provides you with the following constructor.
AtomProperties *properties = [[AtomProperties alloc] initWithDedicatedHostName:@"<#DedicatedIP/Host#>" protocol:@"<#protocol#>"];
[[AtomManager sharedInstance] connectWithProperties:properties completion:^(NSString *success) {}
errorBlock:^(NSError *error) {}];
;
Connection with Real-time Optimized Servers
This one is same as the first one i.e. “Connection with Parameters” with a slight addition of using Real-time optimized servers best from your user’s location. You just need to set this property to TRUE and rest will be handled by the ATOM SDK.
AtomProperties* properties = [[AtomProperties alloc] initWithCountry:@"<#country#>" protocol:@"<#protocol#>"];
[properties setUseOptimization:YES];
[[AtomManager sharedInstance] connectWithPropertiesconnectWithProperties:properties completion:^(NSString *success) {}
errorBlock:^(NSError *error) {}];
If you want to show your user the best location for him on your GUI then ATOM SDK have it ready for you as well! ATOM SDK has a method exposed namely “getOptimizedCountries” which adds a property “RoundTripTime” in the country object which has the real-time latency of all countries from your user’s location (only if ping is enabled on your user’s system and ISP doesn’t blocks any of our datacenters). You can use this property to find the best speed countries from your user’s location.
Connection with Smart Dialing
“Connection with Parameters” with a slight addition of using smart dialing to connect. You just need to call "withSmartDialing" and rest will handled by the ATOM SDK.
AtomProperties* properties = [[AtomProperties alloc] initWithCountry:@"<#country#>" protocol:@"<#protocol#>"];
[properties setUseSmartDialing:YES];
[[AtomManager sharedInstance] connectWithProperties:properties completion:^(NSString *success) {}
errorBlock:^(NSError *error) {}];
For more information, please see the inline documentation of AtomProperties Class.
Connection with Multiple Protocols (Auto-Retry Functionality)
You can provide three protocols at max so ATOM SDK can attempt automatically on your behalf to get your user connected with the Secondary or Tertiary protocol if your base Protocol fails to connect.
properties.secondaryProtocol = @"<protocol2>"; properties.tertiaryProtocol = @"<protocol3>";
Cancel VPN Connection
You can cancel connection between dialing process by calling the cancelVPN method.
[[AtomManager sharedInstance] cancelVPN];
Disconnect VPN Connection
To disconnect, simply call the disconnectVPN method of AtomManager.
[[AtomManager sharedInstance] disconnectVPN];
Distributing to App Store
While distributing application to app store developer should add Run Script in Build phase before the app can be submitted to the iTunes App Store. This type of “Fat Binary” framework will not pass the App Store validation process, so we will need to strip the simulator architecture version from the framework using the following shell script. When you build and archive the app for release, the fat binaries will be stripped and the app can be submitted to the iTunes App Store.
Select the Project in xcode, Choose Target → Project Name → Select Build Phases → Press “+” → New Run Script Phase → Name the Script as “Remove Unused Architectures Script”.
FRAMEWORK="AtomSDK"
echo "Trimming $FRAMEWORK..."
FRAMEWORK_EXECUTABLE_PATH="${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}/$FRAMEWORK.framework/$FRAMEWORK"
EXTRACTED_ARCHS=()
for ARCH in $ARCHS
do
echo "Extracting $ARCH..."
lipo -extract "$ARCH" "$FRAMEWORK_EXECUTABLE_PATH" -o "$FRAMEWORK_EXECUTABLE_PATH-$ARCH"
EXTRACTED_ARCHS+=("$FRAMEWORK_EXECUTABLE_PATH-$ARCH")
done
echo "Merging binaries..."
lipo -o "$FRAMEWORK_EXECUTABLE_PATH-merged" -create "${EXTRACTED_ARCHS[@]}"
rm "${EXTRACTED_ARCHS[@]}"
rm "$FRAMEWORK_EXECUTABLE_PATH"
mv "$FRAMEWORK_EXECUTABLE_PATH-merged" "$FRAMEWORK_EXECUTABLE_PATH"
echo "Done."
Thats all !! This run script removes the unused simulator architectures only while pushing the application to the App Store.
NOTE: The current version of the VPN Atom SDK uses the following library under the hood:
- NEVPNManager