PureWL VPN SDK & API

https://www.purewl.com/developer/
Admin
PureWL VPN SDK & API is a developer platform that enables seamless integration of enterprise-grade...
Tokens:63,347
Snippets:528
Trust Score:9.2
Update:8 months ago
Show doc for...
Tokens:
Raw
### Start VPN Tunnel Delegate (Swift)

Source: https://www.purewl.com/developer/guides/sdks/macos-sdk

This Swift code implements the `startTunnel` delegate method for the `PacketTunnelProvider`. This method is invoked when the VPN connection enters a starting state, allowing for custom setup logic.

```Swift
override func startTunnel(options: [String : NSObject]?, completionHandler: @escaping (Error?) -> Void) {
    super.startTunnel(options: options, completionHandler: completionHandler)
}
```

--------------------------------

### Install Atom SDK via NuGet

Source: https://www.purewl.com/developer/guides/sdks/windows-sdk

This command installs the latest version of the Atom Network SDK for .NET applications using the NuGet package manager. Ensure you have NuGet Package Manager installed and configured in your Visual Studio environment.

```powershell
NuGet\Install-Package Atom.SDK.Net -Version 5.1.0
```

--------------------------------

### Get Optimized Server Request Example (JSON)

Source: https://www.purewl.com/developer/guides/api/api-reference/speedtest-get-fastest-server

This snippet demonstrates a sample JSON payload for requesting an optimized VPN server. It includes essential parameters like access token, country, protocol, and user details. Ensure all required fields are populated for a successful request.

```json
{
  "X-AccessToken": "YOUR_ACCESS_TOKEN",
  "sCountrySlug": "us",
  "iCityId": 12345,
  "iResellerId": 67890,
  "sProtocolSlug1": "udp",
  "sProtocolSlug2": "tcp",
  "sProtocolSlug3": "ws",
  "sUsername": "vpn_user",
  "sDeviceType": "windows",
  "iChannelId": "channel_123",
  "iMcs": 1,
  "iMultiPort": 0,
  "sDataCenters": "[123,122]",
  "sIp": "192.168.1.1",
  "iNatting": 1,
  "aServerFilter": "[{ 'nasidentifier' : 'lux-01-01-01','type' : 'include'}]",
  "aTagsFilter": "["TAG_RAM_BASED", "TAG_OVPN_OBF"]",
  "bIsExperimentUser": 0,
  "sClientPublicKey": "YOUR_PUBLIC_KEY",
  "sSdkVersion": "1.0.0"
}
```

--------------------------------

### Initialize Atom SDK Configuration

Source: https://www.purewl.com/developer/guides/sdks/windows-sdk

This C# code snippet demonstrates how to initialize the Atom SDK by creating an instance of `AtomConfiguration`. It requires essential parameters such as a secret key, installed service name, installed directory folder name, and a custom VPN interface name. The `VpnInterfaceName` property is crucial for creating the VPN network interface, and `BaseUrl` can be optionally set for specific configurations.

```csharp
var atomConfiguration = new AtomConfiguration(@"SECRETKEY_GOES_HERE", @"INSTALLED_SERVICE_NAME_GOES_HERE", @"INSTALLED_DIRECTORY_FOLDER_NAME_GOES_HERE", @"CUSTOM_VPN_INTERFACE_NAME_GOES_HERE");
atomConfiguration.VpnInterfaceName = "AtomDemo";
atomConfiguration.BaseUrl = new Uri("YOUR_BASE_URL"); // Optional
var atomManagerInstance = AtomManager.Initialize(atomConfiguration);
```

--------------------------------

### NetworkExtension Setup for OpenVPN

Source: https://www.purewl.com/developer/guides/sdks/ios-sdk

Information on setting up NetworkExtension for OpenVPN TCP and UDP, including compatibility details.

```APIDOC
## How to setup NetworkExtension for OpenVPN TCP, OpenVPN UDP & Wireguard

### Description
Guidance on setting up NetworkExtension for various VPN protocols.

### Method
N/A

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
#### Success Response (N/A)
N/A

#### Response Example
N/A

## Compatibility For OpenVPN TCP & OpenVPN UDP

### Description
Compatibility information for OpenVPN TCP and OpenVPN UDP protocols.

### Method
N/A

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
#### Success Response (N/A)
- Compatible with Xcode 15.3, iOS 12.0, macOS 10.15, tvOS 17.0 and later.

#### Response Example
N/A
```

--------------------------------

### Generate VPN Account (Request Example)

Source: https://www.purewl.com/developer/guides/api/api-reference/vpn-account-management-vam/generate

This example demonstrates how to make a POST request to the VPN Account Management API to generate a new VPN account. It includes common parameters like X-AccessToken, uuid, and optional preferences.

```bash
curl --location --request POST '<base url>/vam/v2/generate' \
--header 'X-AccessToken: YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "uuid": "your_unique_uuid",
    "period": "365",
    "preferences": {
        "multi_login": 5,
        "session_limit": 50,
        "country": [1, 2, 3],
        "city": [1, 2, 3],
        "protocol": [1, 2, 3]
    },
    "isDedicated": false,
    "oneLoginScheme": false
}'
```

--------------------------------

### Get Access Token

Source: https://www.purewl.com/developer/guides/api/how-web-services-api-works

Instructions on how to obtain an access token using your Secret Key.

```APIDOC
## POST /oauth/token

### Description
Fetches an access token required for most API calls. This token is generated using your Secret Key.

### Method
POST

### Endpoint
`/oauth/token`

### Parameters
#### Request Body
- **secret_key** (string) - Required - Your API Secret Key obtained from the Partner's Console.
- **grant_type** (string) - Required - Should be set to `client_credentials`.

### Request Example
```json
{
  "secret_key": "YOUR_SECRET_KEY",
  "grant_type": "client_credentials"
}
```

### Response
#### Success Response (200 OK)
- **access_token** (string) - The generated access token.
- **expires_in** (integer) - The token's validity period in seconds.
- **token_type** (string) - The type of token, usually `Bearer`.

#### Response Example
```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600,
  "token_type": "Bearer"
}
```
```

--------------------------------

### Packet Tunnel Provider Delegates (Swift)

Source: https://www.purewl.com/developer/guides/sdks/ios-sdk

This section provides Swift code examples for implementing essential delegates within a Packet Tunnel Provider. These delegates handle the lifecycle events of the VPN tunnel, including starting, stopping, and inter-app communication.

```swift
override func startTunnel(options: [String : NSObject]?, completionHandler: @escaping (Error?) -> Void) {
    super.startTunnel(options: options, completionHandler: completionHandler)
}
```

```swift
override func stopTunnel(with reason: NEProviderStopReason, completionHandler: @escaping () -> Void) {
    super.stopTunnel(with: reason, completionHandler: completionHandler)
}
```

```swift
override func handleAppMessage(_ messageData: Data, completionHandler: ((Data?) -> Void)? = nil) {
    super.handleAppMessage(messageData, completionHandler: completionHandler)
}
```

--------------------------------

### Get Protocols (v3) Sample Response

Source: https://www.purewl.com/developer/guides/api/api-reference/inventory-management/protocols

This is a sample JSON response for the Get Protocols (v3) API. It includes header information and a body containing an array of protocol objects, detailing supported VPN protocols for a given device type.

```json
{
  "header": {
    "response_code": 1,
    "message": "success"
  },
  "body": {
    "protocols": [
      {
        "id": 1,
        "name": "TCP",
        "protocol": "TCP",
        "number": 1,
        "port_number": 0,
        "protocol_switch": [],
        "is_multiport": 0,
        "multiport_range": 0
      }
    ]
  }
}
```

--------------------------------

### Enable Tracker / Ad Blocker

Source: https://www.purewl.com/developer/guides/sdks/android-sdk

Guides on how to enable the Tracker and Ad Blocker features using the `VPNProperties` builder. This enhances user privacy by blocking unwanted scripts and advertisements.

```APIDOC
## Enable Tracker / Ad Blocker

### Description
Guides on how to enable the Tracker and Ad Blocker features using the `VPNProperties` builder. This enhances user privacy by blocking unwanted scripts and advertisements.

### Method
`vpnPropertiesBuilder.withAtomShield(@NonNull List<AtomShieldFeature>)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
**AtomShieldFeature** (Enum List) - Required - A list of `AtomShieldFeature` enum values to enable. Supported options are `TRACKER` and `AD_BLOCKER`.

### Request Example
```java
// To enable both Tracker and Ad Blocker
List<AtomShieldFeature> shieldFeatures = Arrays.asList(AtomShieldFeature.TRACKER, AtomShieldFeature.AD_BLOCKER);
VPNProperties vpnProperties = vpnPropertiesBuilder
    .withAtomShield(shieldFeatures)
    // ... other configurations
    .build();

// To enable only Ad Blocker
List<AtomShieldFeature> adBlockerOnly = Collections.singletonList(AtomShieldFeature.AD_BLOCKER);
VPNProperties vpnPropertiesAdBlocker = vpnPropertiesBuilder
    .withAtomShield(adBlockerOnly)
    // ... other configurations
    .build();
```

### Response
#### Success Response (200)
- The `VPNProperties` object will be configured with the specified Atom Shield features enabled. These features will be active when the VPN connection is established.
```

--------------------------------

### Fetch Recommended Country

Source: https://www.purewl.com/developer/guides/sdks/windows-sdk

Get the recommended country for a user's location based on ATOM SDK's analysis.

```csharp
var recommendedCountry = AtomManagerInstance.GetRecommendedCountry();
```

--------------------------------

### Get Fastest Server DNS

Source: https://www.purewl.com/developer/guides/api/how-web-services-api-works

Information on retrieving the DNS of the fastest available VPN server.

```APIDOC
## GET /server/fastest

### Description
Retrieves the DNS address of the fastest available VPN server based on network conditions and user location. This endpoint is recommended for SDK implementations using the Ping Datacenter Algorithm.

### Method
GET

### Endpoint
`/server/fastest`

### Parameters
#### Query Parameters
- **protocol** (string) - Optional - The desired VPN protocol (e.g., 'OpenVPN', 'WireGuard'). If not specified, a default protocol will be used.
- **datacenter_ids** (array of strings) - Optional - A list of specific datacenter IDs to consider for the speed test.

### Request Example
```
https://atomapi.com/server/fastest?protocol=OpenVPN
```

### Response
#### Success Response (200 OK)
- **dns_address** (string) - The DNS address of the fastest VPN server.
- **server_id** (string) - The unique identifier of the selected server.
- **protocol** (string) - The protocol used by the selected server.

#### Response Example
```json
{
  "dns_address": "us-east-1.vpn.purewl.com",
  "server_id": "srv-abc123xyz",
  "protocol": "OpenVPN"
}
```
```

--------------------------------

### Configure On-Demand Custom VPN Rules (Objective-C)

Source: https://www.purewl.com/developer/guides/sdks/ios-sdk

This example demonstrates how to configure custom on-demand VPN rules using the Atom SDK. It covers enabling on-demand features, defining connection and disconnection rules based on Wi-Fi SSIDs and cellular interfaces, and applying the configuration. Ensure that `onDemandRulesEnabled` is set to YES for functionality.

```objective-c
// Create and configure On-Demand settings
AtomOnDemandConfiguration *onDemandConfiguration = [[AtomOnDemandConfiguration alloc] init];
onDemandConfiguration.onDemandRulesEnabled = YES;
onDemandConfiguration.isOnDemandCustomRulesEnabled = YES;

// Create rules array
NSMutableArray *rules = [NSMutableArray new];

// Rule 1: Connect VPN on untrusted Wi-Fi networks
AtomOnDemandConnectRule *connectRule = [[AtomOnDemandConnectRule alloc] 
    initWithSSIDMatch:@[@"PublicWiFi", @"CoffeeShop"]
    interfaceType:AtomOnDemandInterfaceTypeWifi];
[rules addObject:connectRule];

// Rule 2: Disconnect VPN on trusted Wi-Fi networks
AtomOnDemandDisconnectRule *disconnectRule = [[AtomOnDemandDisconnectRule alloc] 
    initWithSSIDMatch:@[@"HomeNetwork", @"OfficeNetwork"]
    interfaceType:AtomOnDemandInterfaceTypeWifi];
[rules addObject:disconnectRule];

// Rule 3: Connect VPN on cellular networks
AtomOnDemandConnectRule *cellularRule = [[AtomOnDemandConnectRule alloc] 
    initWithSSIDMatch:nil 
    interfaceType:AtomOnDemandInterfaceTypeCellular];
[rules addObject:cellularRule];

// Set rules
onDemandConfiguration.OnDemandCustomRules = rules;

// Apply configuration
[[AtomManager sharedInstance] setOnDemandConfiguration:onDemandConfiguration];
[[AtomManager sharedInstance] updateOnDemandVpnStatusWithCompletion:^(NSString * _Nullable success) {
    NSLog(@"On Demand Custom Rules updated successfully");
} errorBlock:^(NSError * _Nullable error) {
    NSLog(@"Error updating On Demand Rules: %@", error.localizedDescription);
}];
```

--------------------------------

### Enable VPN Account API Request (Example)

Source: https://www.purewl.com/developer/guides/api/api-reference/vpn-account-management-vam/enable-account

This snippet demonstrates how to enable a VPN account using the provided API endpoint. It includes the necessary headers and request body parameters. The response indicates the success or failure of the operation.

```json
{
  "header": {
    "response_code": 1,
    "message": "VPN account has been enabled successfully"
  },
  "body": {
    "vpnUsername": "xxxxx",
    "statusUpdated": "Enable"
  }
}
```

--------------------------------

### Sample Successful Server Response

Source: https://www.purewl.com/developer/guides/api/api-reference/speedtest-get-fastest-server

This is a sample JSON response indicating a successful retrieval of server information. It includes details about the server's host, port, protocol, country, and other configuration parameters.

```json
{
  "header": {
    "code": 1,
    "message": "Success"
  },
  "body": {
    "servers": [
      {
        "host": "xxxxxx.pointtoserver.com",
        "hub_key": "",
        "acknowledgement_server": "xxxxxx.pointtoserver.com",
        "port_number": "30",
        "protocol_no": 8,
        "country": "US",
        "multiport": 0,
        "server_type": "linux",
        "speedtest_method": "DC",
        "filter_success": false,
        "ram_based": 0,
        "ovpn_obf": 0,
        "ip_translation": 1,
        "nasidentifer": "lux-01-xx-xx",
        "iperf_client_ip": "...........com",
        "iperf_port_range": "5201:5210",
        "iperf_client_status": 0,
        "configuration_version": "",
        "configuration": "",
        "Wireguard_configuration": "",
        "Is_experiment_server": ""
      }
    ]
  }
}
```

--------------------------------

### Get Countries (v2) API Request Example

Source: https://www.purewl.com/developer/guides/api/api-reference/inventory-management/countries

This snippet illustrates how to call the Get Countries API (v2) using a GET request to fetch subscribed countries for a given device. Similar to v3, it requires an X-AccessToken header and the sDeviceType in the URL path. The API returns a JSON response with country information.

```http
GET /inventory/v2/countries/ios HTTP/1.1
Host: <base url>
X-AccessToken: YOUR_ACCESS_TOKEN
```

--------------------------------

### Fetch Available Protocols

Source: https://www.purewl.com/developer/guides/sdks/windows-sdk

Retrieve a list of supported VPN protocols from the ATOM SDK.

```csharp
var protocols = atomManagerInstance.GetProtocols();
```

--------------------------------

### Get Countries (v3) API Request Example

Source: https://www.purewl.com/developer/guides/api/api-reference/inventory-management/countries

This snippet demonstrates how to make a GET request to the Get Countries API (v3) to retrieve a list of subscribed countries for a specific device type. It requires an access token in the header and the device type in the path. The response is a JSON object containing country details.

```http
GET /inventory/v3/countries/android HTTP/1.1
Host: <base url>
X-AccessToken: YOUR_ACCESS_TOKEN
```

--------------------------------

### Connect to VPN with Parameters

Source: https://www.purewl.com/developer/guides/sdks/windows-sdk

Initiate a VPN connection by providing Country and Protocol objects to the Connect method. This method triggers event updates for connection status and potential errors.

```csharp
var vpnProperties = new VPNProperties(Country country, Protocol protocol);
atomManagerInstance.Connect(properties);
```

--------------------------------

### Connect with Real-time Optimized Servers (Java)

Source: https://www.purewl.com/developer/guides/sdks/android-sdk

Establishes a VPN connection using real-time optimized servers to provide the best performance based on the user's location. This method leverages the `withOptimization()` feature of the ATOM SDK. Ensure the ATOM SDK is properly initialized.

```java
VPNProperties.Builder vpnPropertiesBuilder = new VPNProperties.Builder(Country country, Protocol protocol).withOptimization();
VPNProperties vpnProperties = vpnPropertiesBuilder.build();

atomManager.connect(this, vpnProperties);

```

--------------------------------

### Change VPN Account Password API Request (Example)

Source: https://www.purewl.com/developer/guides/api/api-reference/vpn-account-management-vam/change-password

This example demonstrates how to make a PUT request to change a VPN account password using the specified API endpoint. It includes the necessary headers and the JSON payload with VPN username and new password details. Ensure the X-AccessToken is valid and retrieved from the Get Access Token endpoint.

```http
PUT /vam/v2/changePassword HTTP/1.1
Host: <base url>
Content-Type: application/json
X-AccessToken: <your_access_token>

{
  "vpnUsername": "user123",
  "newPassword": "StrongP@ssw0rd!",
  "confirmNewPassword": "StrongP@ssw0rd!"
}
```

--------------------------------

### Connect with Parameters

Source: https://www.purewl.com/developer/guides/sdks/ios-sdk

Initiate a VPN connection using specified `AtomProperties` (country and protocol).

```APIDOC
## 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.

```objectivec
AtomProperties* properties = [[AtomProperties alloc] initWithCountry:@"<#country#>" protocol:@"<#protocol#>"];

[[AtomManager sharedInstance] connectWithProperties:properties completion:^(NSString *success) {
  // Handle successful connection
} errorBlock:^(NSError *error) {
  // Handle connection error
}];
```
```

--------------------------------

### Get Optimized Server Response

Source: https://www.purewl.com/developer/guides/api/api-reference/speedtest-get-fastest-server

This is a sample response structure for the 'Get Optimized Server' endpoint, detailing the available server information.

```APIDOC
## GET /websites/purewl_developer/servers/optimized

### Description
Retrieves a list of optimized servers based on provided criteria.

### Method
GET

### Endpoint
`/websites/purewl_developer/servers/optimized`

### Parameters

#### Query Parameters
- **country** (string) - Optional - The country to filter servers by.
- **protocol** (integer) - Optional - The protocol number to filter servers by.

### Request Example
```bash
GET /websites/purewl_developer/servers/optimized?country=US&protocol=8
```

### Response
#### Success Response (200)
- **header** (object)
  - **code** (integer) - Success code, typically 1.
  - **message** (string) - Success message, typically "Success".
- **body** (object)
  - **servers** (array)
    - **host** (string) - The hostname of the server.
    - **hub_key** (string) - The hub key for the server.
    - **acknowledgement_server** (string) - The acknowledgement server address.
    - **port_number** (string) - The port number for the server.
    - **protocol_no** (integer) - The protocol number.
    - **country** (string) - The country the server is located in.
    - **multiport** (integer) - Indicates if the server supports multi-port.
    - **server_type** (string) - The type of server (e.g., "linux").
    - **speedtest_method** (string) - The speedtest method used by the server.
    - **filter_success** (boolean) - Indicates if the filter was successful.
    - **ram_based** (integer) - Indicates if the server is RAM-based.
    - **ovpn_obf** (integer) - Indicates if OpenVPN obfuscation is enabled.
    - **ip_translation** (integer) - Indicates if IP translation is enabled.
    - **nasidentifer** (string) - The NAS identifier.
    - **iperf_client_ip** (string) - The IP address for the iPerf client.
    - **iperf_port_range** (string) - The port range for iPerf.
    - **iperf_client_status** (integer) - The status of the iPerf client.
    - **configuration_version** (string) - The configuration version.
    - **configuration** (string) - The server configuration.
    - **Wireguard_configuration** (string) - The WireGuard configuration.
    - **Is_experiment_server** (string) - Indicates if it's an experimental server.

#### Response Example
```json
{
  "header": {
    "code": 1,
    "message": "Success"
  },
  "body": {
    "servers": [
      {
        "host": "xxxxxx.pointtoserver.com",
        "hub_key": "",
        "acknowledgement_server": "xxxxxx.pointtoserver.com",
        "port_number": "30",
        "protocol_no": 8,
        "country": "US",
        "multiport": 0,
        "server_type": "linux",
        "speedtest_method": "DC",
        "filter_success": false,
        "ram_based": 0,
        "ovpn_obf": 0,
        "ip_translation": 1,
        "nasidentifer": "lux-01-xx-xx",
        "iperf_client_ip": "...........com",
        "iperf_port_range": "5201:5210",
        "iperf_client_status": 0,
        "configuration_version": "",
        "configuration": "",
        "Wireguard_configuration": "",
        "Is_experiment_server": ""
      }
    ]
  }
}
```
```

--------------------------------

### POST /vam/v3/create

Source: https://www.purewl.com/developer/guides/api/api-reference/vpn-account-management-vam/create-vpn-account

Use this API to create a VPN account by supplying a UUID as a mandatory parameter. It returns a JSON object with the VPN username, password, and expiry date.

```APIDOC
## POST /vam/v3/create

### Description
Creates a VPN account with specified parameters, returning credentials and expiry information.

### Method
POST

### Endpoint
<base url>/vam/v3/create

### Parameters
#### Header Parameters
- **X-AccessToken** (String) - Required - `accessToken` retrieved from Get Access Token endpoint

#### Request Body
- **uuid** (String) - Required - A universally unique identifier can be any string, email, or unique word.
- **period** (String) - Optional - Account period. The maximum is 3700.
- **preferences** (JSON) - Optional - A structured JSON to specify allowed options such as multi-login limit and locations for the VPN account. Sample JSON: {"multi_login":5,"session_limit":50,"country":[1,2,3],"city":[1,2,3],"protocol":[1,2,3]}
- **preferences_format** (JSON) - Optional - Format of the preferences and its value should always be **key**
- **isDedicated** (Boolean) - Optional - A boolean (True or False) that VPN account will be dedicated or shared. Default: false
- **dedicatedCountry** (String) - Optional - If `isDedicated` is true, this parameter is mandatory and should contain the country ISO code, indicating that this VPN account will have a dedicated IP in that country. Supported countries include: US, GB, CA, DE, AU, HK, NL, SG , NZ and MT.
- **oneLoginScheme** (Boolean) - Optional - 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) - Optional - If `oneLoginScheme` is true, then the VPN username is mandatory and must not exceed 20 characters.
- **vpnPassword** (String) - Optional - If `oneLoginScheme` is true then VPN password is mandatory to provide. Minimum 12, maximum 32 characters. Must contain at least one uppercase letter, one lowercase letter, one number, and one special character (!@#$%^&*,.:{}). Avoid using non-ASCII characters.
- **subscriptionType** (String) - Optional - Account subscription type (**trial** , **paid** and **freemium**). Default is paid

### Request Example
```json
{
  "uuid": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "period": "365",
  "preferences": {
    "multi_login": 5,
    "session_limit": 50,
    "country": [1, 2, 3]
  },
  "preferences_format": "key",
  "isDedicated": false,
  "oneLoginScheme": false,
  "subscriptionType": "paid"
}
```

### Response
#### Success Response (200)
- **header** (JSON) - A JSON object that details the return code and message.
- **body** (JSON) - A JSON object containing the VPN username, password, and expiry date. If the account is dedicated, it will also include the dedicated IP and dedicated host.

#### Response Example
```json
{
  "header": {
    "response_code": 1,
    "message": "VPN account has been created successfully"
  },
  "body": {
    "vpnUsername": "xxxxxxxx",
    "vpnPassword": "xxxxxxxx",
    "expiryDate": "xxxxxxxx"
  }
}
```

### Possible API error codes
- **11001**: The provided uuid already exists.
- **11001**: The vpnUsername field is required when one login scheme is 1.
- **11001**: Period must be a number between 1 and 10950.
- **60003**: Accounts can not be exceed subscribed no of accounts.
- **60004**: Couldn’t Verify UUID.
- **100028**: This username is not available. Please try again with different username.
```

--------------------------------

### Get Protocols (v2) Sample Response

Source: https://www.purewl.com/developer/guides/api/api-reference/inventory-management/protocols

This is a sample JSON response for the Get Protocols (v2) API. It provides header details and a body containing a list of protocol objects, similar to v3, but with a slightly different header structure.

```json
{
  "header": {
    "code": 1,
    "message": "success",
    "response_code": 1
  },
  "body": {
    "protocols": [
      {
        "id": 1,
        "name": "TCP",
        "protocol": "TCP",
        "number": 1,
        "port_number": 0,
        "is_multiport": 0,
        "multiport_range": 0,
        "protocol_switch": []
      }
    ]
  }
}
```

--------------------------------

### Initialize ATOM SDK with Configuration

Source: https://www.purewl.com/developer/guides/sdks/macos-sdk

Initializes the ATOM SDK using AtomConfiguration. Requires a secret key and VPN interface name. The configuration also includes optional bundle identifiers for network extensions. This is a singleton pattern, so it must be initialized before use.

```objectivec
AtomConfiguration *atomConfiguration= [[AtomConfiguration alloc] init];
atomConfiguration.secretKey = @"SECRETKEY_GOES_HERE";
atomConfiguration.vpnInterfaceName = @"Atom";
atomConfiguration.tunnelProviderBundleIdentifier = @"ENTER_YOUR _NETWORK_EXTENSION_BUNDLE_ID";
atomConfiguration.wireGuardTunnelProviderBundleIdentifier = @"ENTER_YOUR_WIREGUARD_NETWORK_EXTENSION_BUNDLE_ID";
[AtomManager sharedInstanceWithAtomConfiguration:atomConfiguration];
```

--------------------------------

### Connect with Parameters

Source: https://www.purewl.com/developer/guides/sdks/macos-sdk

Establishes a connection by providing country and protocol objects.

```APIDOC
## Connect with Parameters

### Description
Initiates a VPN connection using specified country and protocol parameters. Events will be triggered upon state changes and potential errors.

### Method
POST

### Endpoint
`/connect`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **properties** (AtomProperties) - Required - An object containing connection properties like country and protocol.
  - **country** (NSString) - Required - The country code for the connection.
  - **protocol** (NSString) - Required - The protocol to use for the connection.

### Request Example
```objectivec
AtomProperties* properties = [[AtomProperties alloc] initWithCountry:@"<#country#>" protocol:@"<#protocol#>"];

[[AtomManager sharedInstance] connectWithProperties:properties 
    completion:^(NSString *success) {
        // Handle successful connection
    } 
    errorBlock:^(NSError *error) {
        // Handle connection error
    }];
```

### Response
#### Success Response (200)
- **success** (NSString) - A message indicating a successful connection.

#### Response Example
```json
{
  "success": "Connection established successfully."
}
```
```

--------------------------------

### GET /inventory/v2/countries/<sDeviceType>

Source: https://www.purewl.com/developer/guides/api/api-reference/inventory-management/countries

Retrieves a list of subscribed countries for a specific device type using v2 of the API.

```APIDOC
## GET /inventory/v2/countries/<sDeviceType>

### Description
Use this API to get a complete list of subscribed Countries. Returns a JSON object that contains the Countries.

### Method
GET

### Endpoint
/inventory/v2/countries/<sDeviceType>

### Parameters
#### Header Parameters
- **X-AccessToken** (String) - Required - `accessToken` retrieved from Get Access Token endpoint

#### Path Parameters
- **sDeviceType** (String) - Required - Type of device. Possible values: **android** | **ios** | **mac** | **windows**

### Response
#### Success Response (200)
- **header** (JSON) - JSON object that describes return code and message.
- **body** (JSON) - JSON object that returns countries array containing objects.
  - **countries** (Array) - Array of objects that contains details related to country.

### Response Example
```json
{
  "header": {
    "code": 1,
    "message": "success",
    "response_code": 1
  },
  "body": {
    "countries": [
      {
        "id": 254,
        "country": "US",
        "name": "United States",
        "iso_code": "US",
        "latitude": 37.090240000000001,
        "longitude": -95.712890999999999,
        "is_smart_dns": 0,
        "is_virtual": 0,
        "rank": 0,
        "is_freemium": true,
        "recommended_protocol": "IKEV",
        "data_centers": [],
        "protocols": [
          {
            "number": 1,
            "protocol": "PPTP",
            "dns": [
              {
                "configuration_version": "",
                "name": "**.********.com",
                "type": "primary",
                "acknowledgement_server": "**.********.com",
                "port_number": 0,
                "is_multiport": 0,
                "multiport_range": "80",
                "ip_translation": "nat",
                "tags": []
              },
              {
                "number": 8,
                "protocol": "TCP",
                "dns": [
                  {
                    "configuration_version": "2.0",
                    "name": "**.********.com",
                    "type": "primary",
                    "acknowledgement_server": "**.********.com",
                    "port_number": 80,
                    "is_multiport": 0,
                    "multiport_range": "80, 5500-30000",
                    "ip_translation": "nat",
                    "tags": []
                  }
                ]
              }
            ],
            "features": [
              "OVPN_OBF",
              "p2p",
              "QR"
            ]
          }
        ]
      }
    ]
  }
}
```
```

--------------------------------

### Resume VPN Connection and Handle Events (C#)

Source: https://www.purewl.com/developer/guides/sdks/windows-sdk

Demonstrates how to resume a VPN connection and subscribe to relevant events like Connected and DialError. The Resume method initiates the resume process, while the event handlers provide feedback on success or failure.

```csharp
atomManagerInstance.Connected += AtomManager_Connected;
atomManagerInstance.DialError += AtomManager_DialError;

void Resume()
{
    AtomManagerInstance.Resume();
}

private void AtomManager_Connected(object sender, ConnectedEventArgs e)
{
    // VPN resumed successfully
}

private void AtomManager_DialError(object sender, DialErrorEventArgs e)
{
    // Handle resume error
}
```

--------------------------------

### Initialize AtomSDK Configuration in Objective-C

Source: https://www.purewl.com/developer/guides/sdks/ios-sdk

This Objective-C code demonstrates how to initialize the ATOM SDK with a secret key, VPN interface name, and tunnel provider bundle identifiers. The ATOM SDK is a singleton and must be initialized before use.

```objectivec
AtomConfiguration *atomConfiguration= [[AtomConfiguration alloc] init];
    atomConfiguration.secretKey = @"SECRETKEY_GOES_HERE";
    atomConfiguration.vpnInterfaceName = @"Atom";
    atomConfiguration.tunnelProviderBundleIdentifier = @“ENTER_YOUR_NETWORK_EXTENSION_BUNDLE_ID”;
    atomConfiguration.wireGuardTunnelProviderBundleIdentifier = @“ENTER_YOUR_WIREGUARD_NETWORK_EXTENSION_BUNDLE_ID”;

    [AtomManager sharedInstanceWithAtomConfiguration:atomConfiguration];
```

--------------------------------

### GET /inventory/v3/countries/<sDeviceType>

Source: https://www.purewl.com/developer/guides/api/api-reference/inventory-management/countries

Retrieves a list of subscribed countries for a specific device type using v3 of the API.

```APIDOC
## GET /inventory/v3/countries/<sDeviceType>

### Description
Use this API to get a complete list of subscribed Countries. Returns a JSON object that contains the Countries.

### Method
GET

### Endpoint
/inventory/v3/countries/<sDeviceType>

### Parameters
#### Header Parameters
- **X-AccessToken** (String) - Required - `accessToken` retrieved from Get Access Token endpoint

#### Path Parameters
- **sDeviceType** (String) - Required - Type of device. Possible values: **android** | **ios** | **mac** | **windows**

### Response
#### Success Response (200)
- **header** (JSON) - JSON object that describes return code and message.
- **body** (JSON) - JSON object that returns countries array containing objects.
  - **countries** (Array) - Array of objects that contains details related to country.

### Response Example
```json
{
  "header": {
    "code": 1,
    "message": "success",
    "response_code": 1
  },
  "body": {
    "countries": [
      {
        "id": 254,
        "country": "US",
        "name": "United States",
        "iso_code": "US",
        "latitude": 37.090240000000001,
        "longitude": -95.712890999999999,
        "is_smart_dns": 0,
        "is_virtual": 0,
        "is_freemium": true,
        "rank": 0,
        "recommended_protocol": "IKEV",
        "data_centers": [],
        "protocols": [
          {
            "number": 1,
            "protocol": "PPTP",
            "dns": [
              {
                "configuration_version": "",
                "name": "**.********.com",
                "type": "primary",
                "acknowledgement_server": "**.********.com",
                "port_number": 0,
                "is_multiport": 0,
                "multiport_range": "80",
                "ip_translation": "nat",
                "tags": []
              },
              {
                "number": 8,
                "protocol": "TCP",
                "dns": [
                  {
                    "configuration_version": "2.0",
                    "name": "**.********.com",
                    "type": "primary",
                    "acknowledgement_server": "**.********.com",
                    "port_number": 80,
                    "is_multiport": 0,
                    "multiport_range": "80, 5500-30000",
                    "ip_translation": "nat",
                    "tags": []
                  }
                ]
              }
            ],
            "features": [
              "OVPN_OBF",
              "p2p",
              "QR"
            ]
          }
        ]
      }
    ]
  }
}
```
```

--------------------------------

### Get Cities (v3) Sample Response

Source: https://www.purewl.com/developer/guides/api/api-reference/inventory-management/cities

This is a sample JSON response for the Get Cities API (v3). It includes header information and a body containing an array of cities with their details, protocols, and data centers. This response is crucial for users to select their desired VPN server location.

```json
{
  "header": {
    "message": "success",
    "response_code": 1
  },
  "body": {
    "cities": [
      {
        "id": 22,
        "name": "Toronto",
        "country_id": 43,
        "country": "CA",
        "is_freemium": false,
        "recommended_protocol": "IKEV",
        "latitude": 43.6535,
        "longitude": -79.3839,
        "data_centers": [],
        "protocols": [
          {
            "number": 8,
            "protocol": "TCP",
            "dns": [
              {
                "configuration_version": "2.0",
                "name": "cato2-auto-tcp.ptoserver.com",
                "type": "primary",
                "port_number": 80,
                "is_multiport": 0,
                "multiport_range": "80, 5500-30000",
                "ip_translation": "nat",
                "tags": []
              }
            ]
          }
        ],
        "features": []
      }
    ]
  }
}
```

--------------------------------

### Get Cities (v2)

Source: https://www.purewl.com/developer/guides/api/api-reference/inventory-management/cities

Retrieves a list of subscribed cities for a specific device type using version 2 of the API.

```APIDOC
## GET /inventory/v2/cities/<sDeviceType>

### Description
Retrieves a list of subscribed cities for a specific device type using version 2 of the API.

### Method
GET

### Endpoint
`/inventory/v2/cities/<sDeviceType>`

### Parameters
#### Path Parameters
- **sDeviceType** (String) - Required - Type of device. Possible values: android, ios, mac, windows

#### Header Parameters
- **X-AccessToken** (String) - Required - Access token retrieved from the Get Access Token endpoint.

### Response
#### Success Response (200)
- **header** (JSON) - JSON object that describes return code and message.
- **body** (JSON) - JSON object that describes the return code and message.
  - **cities** (Array) - JSON object that returns a cities array containing objects.

### Response Example
```json
{
  "header": {
    "message": "success",
    "response_code": 1
  },
  "body": {
    "cities": [
      {
        "id": 22,
        "name": "Toronto",
        "country_id": 43,
        "country": "CA",
        "latitude": 43.6535,
        "longitude": -79.3839,
        "is_freemium": false,
        "recommended_protocol": "IKEV",
        "data_centers": [],
        "protocols": [
          {
            "number": 8,
            "protocol": "TCP",
            "dns": [
              {
                "configuration_version": "2.0",
                "name": "cato2-auto-tcp.ptoserver.com",
                "type": "primary",
                "port_number": 80,
                "is_multiport": 0,
                "multiport_range": "80,5500-30000",
                "ip_translation": "nat",
                "tags": []
              }
            ],
            "features": [
              "OVPN_OBF",
              "QR"
            ]
          }
        ]
      }
    ]
  }
}
```
```

--------------------------------

### Sample JSON Response for Get Countries API

Source: https://www.purewl.com/developer/guides/api/api-reference/inventory-management/countries

This is a sample JSON response structure returned by the Get Countries API (both v3 and v2). It includes a header with status information and a body containing an array of country objects, each with details like ID, country code, name, and protocol information.

```json
{
  "header": {
    "code": 1,
    "message": "success",
    "response_code": 1
  },
  "body": {
    "countries": [
      {
        "id": 254,
        "country": "US",
        "name": "United States",
        "iso_code": "US",
        "latitude": 37.090240000000001,
        "longitude": -95.712890999999999,
        "is_smart_dns": 0,
        "is_virtual": 0,
        "is_freemium": true,
        "rank": 0,
        "recommended_protocol": "IKEV",
        "data_centers": [],
        "protocols": [
          {
            "number": 1,
            "protocol": "PPTP",
            "dns": [
              {
                "configuration_version": "",
                "name": "**.********.com",
                "type": "primary",
                "acknowledgement_server": "**.********.com",
                "port_number": 0,
                "is_multiport": 0,
                "multiport_range": "80",
                "ip_translation": "nat",
                "tags": []
              }
            ]
          },
          {
            "number": 8,
            "protocol": "TCP",
            "dns": [
              {
                "configuration_version": "2.0",
                "name": "**.********.com",
                "type": "primary",
                "acknowledgement_server": "**.********.com",
                "port_number": 80,
                "is_multiport": 0,
                "multiport_range": "80, 5500-30000",
                "ip_translation": "nat",
                "tags": []
              }
            ]
          }
        ],
        "features": [
          "OVPN_OBF",
          "p2p",
          "QR"
        ]
      }
    ]
  }
}
```

--------------------------------

### GET /vam/v2/status

Source: https://www.purewl.com/developer/guides/api/api-reference/vpn-account-management-vam/status

Retrieves the status of a VPN account. This endpoint requires the VPN username as a mandatory query parameter and an access token in the header.

```APIDOC
## GET /vam/v2/status

### Description
Use this API to check VPN account status by providing the VPN username as a mandatory parameter. Returns a JSON object that contains the VPN username and status.

### Method
GET

### Endpoint
/vam/v2/status

### Parameters
#### Header Parameters
- **X-AccessToken** (String) - Required - `accessToken` retrieved from Get Access Token endpoint

#### Query Parameters
- **vpnUsername** (String) - Required - VPN Username for which status needs to be retrieved.

### Response
#### Success Response (200)
- **header** (JSON object) - JSON object that describes return code and message.
  - **response_code** (Integer) - The response code.
  - **message** (String) - The response message.
- **body** (JSON object) - JSON object that contains the vpnUsername and its status.
  - **vpnUsername** (String) - The VPN username.
  - **status** (String) - The status of the VPN account.

#### Response Example
```json
{
  "header": {
    "response_code": 1,
    "message": "VPN account status fetched successfully"
  },
  "body": {
    "vpnUsername": "xxxxxxxx",
    "status": "Enabled:February 26, 2024"
  }
}
```

### Possible API error codes
- **1001**: There is some problem in fetching vpn account status - An error occurred while attempting to fetch the VPN account status.
- **11001**: The provided username is not valid for this reseller - The provided username is not recognized as valid for the associated reseller.
```

--------------------------------

### Get Cities (v2) Sample Response

Source: https://www.purewl.com/developer/guides/api/api-reference/inventory-management/cities

This is a sample JSON response for the Get Cities API (v2). It provides similar information to v3, including header and body with city details, but may have slight variations in the structure or available features compared to v3. This response helps users select VPN server locations.

```json
{
  "header": {
    "message": "success",
    "response_code": 1
  },
  "body": {
    "cities": [
      {
        "id": 22,
        "name": "Toronto",
        "country_id": 43,
        "country": "CA",
        "latitude": 43.6535,
        "longitude": -79.3839,
        "is_freemium": false,
        "recommended_protocol": "IKEV",
        "data_centers": [],
        "protocols": [
          {
            "number": 8,
            "protocol": "TCP",
            "dns": [
              {
                "configuration_version": "2.0",
                "name": "cato2-auto-tcp.ptoserver.com",
                "type": "primary",
                "port_number": 80,
                "is_multiport": 0,
                "multiport_range": "80,5500-30000",
                "ip_translation": "nat",
                "tags": []
              }
            ],
            "features": [
              "OVPN_OBF",
              "QR"
            ]
          }
        ]
      }
    ]
  }
}
```

--------------------------------

### Fetch Available Protocols

Source: https://www.purewl.com/developer/guides/sdks/ios-sdk

Obtain a list of available connection protocols supported by the ATOM SDK.

```APIDOC
## Fetch Protocols

Protocols can be obtained through ATOM SDK as well.

```objectivec
[[AtomManager sharedInstance] getProtocolsWithSuccess:^(NSArray<AtomProtocol *> *success) {
  // Handle success response
} errorBlock:^(NSError *error) {
  // Handle error
}];
```
```
Tokens:
Raw