ATOM - Secure Platform

Web Service API & SDK Integration Guide


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.

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:

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.

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.

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.

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:

  1. Get your Secret Key from Partner’s Console
  2. Get Access Token via Secret key received in First Step
  3. Get Fastest Server DNS using GetServer API
  4. 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://www.secure.com/atom/documentation

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.

To begin with you’ll be needing a Subscribed Partner's account that will allow you to access Atom Platform API.

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.

  1. First, browse to https://www.secure.com/atom/ and login to the platform’s console with your credentials
  2. Go to the section Secret Key
  3. 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.

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

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.

  1. 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.

  2. 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

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

API in this section are related to API Access and Authentication

  1. 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"
        }
    }  
  1. 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": {}
        }
    }
      
  2. 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
            }]
        }
    }
    
      
  3. 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"
            }]
        }]
        }
    }
    
  4. 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": ""
                }]
            }]
        }
    }
    
  5. 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"
                    }
                ]}
            ]}
        }
    }
    
  6. 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
                        }]
                    }]
                }]
            }]
        }
    }
    
  7. 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
                }]
            }
        ]}
    }
    
  8. 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
                }]
            }]
        }
    }
    
  9. 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"
                }]
            }]
        }
    }
    
  10. 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"
            }
        ]}
    }
    
  1. 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"
        }
    }
    
      
  2. 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"
        }
    }
    
  3. 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"
        }
    }
    
  4. 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"
        }
    }
    
  5. 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"
        }
    }
    
  6. 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"
        }
    }
    
  7. 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"
        }
    }
    
  8. 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"
        }
    }
    
  9. 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"
        }
    }
    
  10. 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"
        }
    }
    
  1. 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 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
    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"
            }]
        }
    }
    
  2. 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"
        }
    }
    
  3. 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
  4. 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"
            }]
        }
    }
    

A Software Development Kit is prepared for the following platforms:

  1. Windows
  2. Mac
  3. Android
  4. iOS

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.

Compatibility

  • Compatible with Microsoft Visual Studio 2015 and onwards
  • Minimum .Net Framework 4.5 required
  • Compatible with ATOM SDK Version 1.0.4 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 1.0.4

A configuration file is provided along with the SDK namely “Atom.SDK.Net.dll.config” which needs to be configured to work properly and should be present in the same directory as your installation directory e.g. C:\ProgramFiles\YourSoftware. Default values are pre-filled for the developer ease.

Run Atom.SDK.Installer.exe to install supporting services and drivers. The services will be installed and copied to the paths provided in the config file.

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 = "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.

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 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.

vpnProperties.UseOptimization= true;

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 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.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();

Compatibility

  • Compatible with Xcode 9 and OS X 10.11 and later
  • Compatible with ATOM SDK Version 1.0.4 and onwards

Supported Protocols

  • IPSec

SDK Installation

You can download the latest version of ATOM SDK from HERE.

Getting Started with the Code

To add the SDK in Xcode:

  1. Open your Xcode project.
  2. Add your developer account to Xcode from Preferences -> Account if you didn't add before.
  3. Select General tab from your app target and then set your developer account details.
  4. 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.
  5. Drag and drop AtomSDK.framework into your project.
  6. Go to your project -> General tab from your app target, add the framework using ‘+’ to the Embedded Binaries section.
  7. After the setup is completed, you should be able to use all the classes from the SDK by including it with the #import directive.
  8. 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";
atomConfiguration.baseUrl = [NSURL URLWithString:@"<#YOUR_BASE_URL#>"];
[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:@"" 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 *success) {}
} errorBlock:^(NSError *error) {}];

Fetch Protocols

Protocols can be obtained through ATOM SDK as well.

[[AtomManager sharedInstance] getProtocolsWithSuccess:^(NSArray *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.

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

Compatibility

  • Compatible with Android 4.0/API Level: 14 (ICE_CREAM_SANDWICH) and later
  • Compatible with ATOM SDK Version 1.0.4 and onwards

Supported Protocols

  • TCP
  • UDP
  • IKEV

SDK Installation

You can download the latest version of ATOM SDK from HERE.

Import module aar as library in your project using Android Studio then add it to build.gradle of app

compile project(':AtomSdk-1.0.4')	
Requirements

ATOM SDK requires following libraries to properly build.

compile 'com.google.code.gson:gson:2.8.0'
compile 'com.jakewharton.timber:timber:4.6.0'
compile 'com.squareup.okhttp3:logging-interceptor:3.9.0'
compile 'com.squareup.retrofit2:converter-moshi:2.3.0'
compile 'com.squareup.retrofit2:adapter-rxjava:2.3.0'
compile 'br.com.zbra:android-linq:1.1.0'

You also need to configure the following libraries:

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.

Callbacks to Register

ATOM SDK offers five callbacks to register for the ease of the developer.

  1. onStateChange
  2. onConnected
  3. onDisconnected
  4. onDialError
  5. 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.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.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>() {

            @Override
            public void onSuccess(List 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() {

            @Override
            public void onSuccess(List 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, String ServerType).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 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);

Compatibility

  • Compatible with Xcode 9 and iOS 9 and later
  • Compatible with ATOM SDK Version 1.0.4 and onwards

Supported Protocols

  • IPSec
  • IKEV

SDK Installation

You can download the latest version of ATOM SDK from HERE.

Getting Started with the Code

To add the SDK in Xcode:

  1. Open your Xcode project.
  2. Add your developer account to Xcode from Preferences -> Account if you didn't add before.
  3. Select General tab from your app target and then set your developer account details.
  4. 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.
  5. Drag and drop AtomSDK.framework into your project.
  6. Go to your project -> General tab from your app target, add the framework using ‘+’ to the Embedded Binaries section.
  7. 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.
  8. 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";
    atomConfig.baseUrl = [NSURL URLWithString:@"YOUR_BASE_URL"];
    [AtomManager sharedInstanceWithAtomConfiguration:atomConfig];

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.

  1. atomManagerDidConnect
  2. atomManagerDidDisconnect
  3. atomManagerOnRedialing
  4. 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:@"" 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:@"" protocol:@""];

Fetch Countries

Countries can be obtained through ATOM SDK as well.

[[AtomManager sharedInstance] getCountriesWithSuccess:^(NSArray *success) {}
} errorBlock:^(NSError *error) {}];

Fetch Protocols

Protocols can be obtained through ATOM SDK as well.

[[AtomManager sharedInstance] getProtocolsWithSuccess:^(NSArray *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] 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 “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.

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 = @"";
properties.tertiaryProtocol = @"";
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