CoreAPI

Core methods that used for initialize tunnel

Note:

• The returned structures are intended for internal use and are subject to change at any time.

Login

Logins to the backend for fetch AccessToken, for instance.

var sdk = new SDK();
var loginRequest = new LoginRequest
{
    Method = AuthenticationMethod.Anonymous.ToString(),
    Token = null,
};

var loginResponse = await sdk.LoginAsync(loginRequest).ConfigureAwait(false);
if (loginResponse.Result.Equals(ResponseResult.Ok))
{
    Console.WriteLine(loginResponse.AccessToken);
}

Logout

Logouts from backend.

var sdk = new SDK();
var loginRequest = new LoginRequest
{
    Method = AuthenticationMethod.Anonymous.ToString(),
    Token = null,
};

var loginResponse = await sdk.LoginAsync(loginRequest).ConfigureAwait(false);
var logoutResponse = await sdk.LogoutAsync(loginResponse.AccessToken).ConfigureAwait(false);
Console.WriteLine(logoutResponse.Result);

GetUserInfo

Gets user info, like Name, UserId, DevicesLimit etc.

var sdk = new SDK();
var loginRequest = new LoginRequest
{
    Method = AuthenticationMethod.Anonymous.ToString(),
    Token = null,
};

var loginResponse = await sdk.LoginAsync(loginRequest).ConfigureAwait(false);
var userInfoResponse = await sdk.GetUserInfoAsync(loginResponse.AccessToken).ConfigureAwait(false);
if (userInfoResponse.Result.Equals(ResponseResult.Ok))
{
    Console.WriteLine(userInfoResponse.Name);
}

GetRemainingTraffic

This method allows users to retrieve their remaining traffic balance.

var sdk = new SDK();
var loginRequest = new LoginRequest
{
    Method = AuthenticationMethod.Anonymous.ToString(),
    Token = null,
};

var loginResponse = await sdk.LoginAsync(loginRequest).ConfigureAwait(false);
var getRemainingTrafficResponse = await sdk.GetRemainingTrafficAsync(loginResponse.AccessToken).ConfigureAwait(false);
if (getRemainingTrafficResponse.Result.Equals(ResponseResult.Ok))
{
    Console.WriteLine(getRemainingTrafficResponse.TrafficRemaining);
}

GetLocations

This method is used to retrieve a list of VPN locations and for multi-hop, custom DNS, and VPN profiles functionalities.

var sdk = new SDK();
var loginRequest = new LoginRequest
{
    Method = AuthenticationMethod.Anonymous.ToString(),
    Token = null,
};

var loginResponse = await sdk.LoginAsync(loginRequest).ConfigureAwait(false);

var getLocationsRequest = new GetLocationsRequest
{
    AccessToken = loginResponse.AccessToken,
    Protocol = Core.Model.Enums.Protocol.HydraTcp,
};

var getLocationsResponse = await sdk.GetLocationsAsync(getLocationsRequest).ConfigureAwait(false);

An example response looks as follows:

{
  "DnsServers": [...],
  "Locations": [
    {
      "Description": "Test location 1, includes all servers"
      "Labels": {
        "City": "",
        "Country": "",
        "Subdivision": "",
      },
      "Name": "test-1",
      "Status": "OK",
    },
    ...
  ],
  "Message": "OK",
  "Metadata": {...},
  "Profiles": [],
  "Result": "Ok",
  "VpnCustomLocations": [
    {
      Carrier: {...}
      IsAutomatic: false,
      Location: "test-1",
      ProxyLocation: null,
      ProxyOptimal: false,
      ServerRepresentation: "test-1",
    },
    ...
  ],
}

Connecting to Specific Locations using GetLocations

To connect to a specific location, you can use either the VpnCustomLocations property of the GetLocationsResponse. Here's how you can do it:

var selectedCustomLocation = getLocationsResponse.VpnCustomLocations[0];

• The Locations[0] element points to the same location as VpnCustomLocations[0]. The Locations is useful for finding a location to display based on the connection's location index.

• Only the VpnCustomLocations is used for establishing the connection. The Locations can be useful for displaying the connection location in the user interface.

Searching for a Specific Location

If you want to connect to a location based on its name, you can search through the VpnCustomLocations list:

var locationName = "YOUR_SELECTED_LOCATION";
var selectedLocation = getLocationsResponse.VpnCustomLocations
    .FirstOrDefault(loc => loc.Location == locationName);

if (selectedLocation != null)
{
    // Do something
}
else
{
    Console.WriteLine("Location not found");
}

For more information regarding a feature that automatically selects the best VPN server for your connection, see Optimal Location

GetCredentials

Gets credentials for VPN tunnel, including HydraCertificate, OpenVpnCertificate, UserName and UserPassword etc.

var sdk = new SDK();
var loginRequest = new LoginRequest
{
    Method = AuthenticationMethod.Anonymous.ToString(),
    Token = null,
};

var loginResponse = await sdk.LoginAsync(loginRequest).ConfigureAwait(false);

var getLocationsRequest = new GetLocationsRequest
{
    AccessToken = loginResponse.AccessToken,
    Protocol = Core.Model.Enums.Protocol.HydraTcp,
};

var getLocationsResponse = await sdk.GetLocationsAsync(getLocationsRequest).ConfigureAwait(false);

var getCredentialsRequest = new GetCredentialsRequest
{
    AccessToken = loginResponse.AccessToken,
    VpnNode = getLocationsResponse.VpnCustomLocations.FirstOrDefault(),
    WithCertificate = true,
    Protocol = Core.Model.Enums.Protocol.HydraTcp,
};

var getCredentialsResponse = await sdk.GetCredentialsAsync(getCredentialsRequest).ConfigureAwait(false);
if (getCredentialsResponse.Result.Equals(ResponseResult.Ok))
{
    Console.WriteLine(getCredentialsResponse.Credentials);
}

Since the SDK release 2.25.0 HydraRoutes feature is enabled by default. Option to disable usage of HydraRoutes will be removed in one of the future releases.

This change affects the content of the GetCredentialsResponse Credentials property: Servers list is empty, while HydraRoutesJson is populated. No changes in client code are required.

StartVpn

All protocols (except IPSec) work on the Wintun adapter, which is created anew each time.

var sdk = new SDK();
var loginRequest = new LoginRequest
{
    Method = AuthenticationMethod.Anonymous.ToString(),
    Token = null,
};

var loginResponse = await sdk.LoginAsync(loginRequest).ConfigureAwait(false);

var getLocationsRequest = new GetLocationsRequest
{
    AccessToken = loginResponse.AccessToken,
    Protocol = Core.Model.Enums.Protocol.HydraTcp,
};

var getLocationsResponse = await sdk.GetLocationsAsync(getLocationsRequest).ConfigureAwait(false);
var selectedLocation = getLocationsResponse.VpnCustomLocations.FirstOrDefault();

var getCredentialsRequest = new GetCredentialsRequest
{
    AccessToken = loginResponse.AccessToken,
    VpnNode = selectedLocation,
    WithCertificate = true,
    Protocol = Core.Model.Enums.Protocol.HydraTcp,
};

var getCredentialsResponse = await sdk.GetCredentialsAsync(getCredentialsRequest).ConfigureAwait(false);

var startVpnRequest = new StartVpnRequest()
{
    AccessToken = loginResponse.AccessToken,
    Credentials = getCredentialsResponse.Credentials,
    EnableKillSwitch = false,
    EnableTunnelLogging = false,
    WaitConnected = true,
    AdapterName = "AdapterName",
};

var startVpnResponse = await sdk.StartVpnAsync(startVpnRequest).ConfigureAwait(false);
if (startVpnResponse.Result == ResponseResult.Ok)
{
    Console.WriteLine(startVpnResponse.Message);
}

With "StartVpnRequest" you can send "WaitConnected" flag which means:

True - "StartVpn" method will wait until the tunnel will be connected before sending the response. This value is for backward compatibility with previous versions.

Null/False (default) - "StartVpn" method will send response after connection will be initiated and later it can be canceled by "StopVpn" request. The connection status or error will be received through the 'StateChanged' event.

Also with "StartVpnRequest" you can send "AdapterName" value to specify your own name of the VPN adapter that will be created when connecting to the VPN. Otherwise the SDK will use default adapter names:

• Unified Wintun - for hydra and OpenVPN

• IPsec tunnel - for IPSec

• tunnel - for Wireguard

StartVpnSession

Combines GetCredentialsRequest and StartVpnRequest steps.

Session reconnection functionality is available only with usage of this API method, see the Reconnection strategy article

var sdk = new SDK();
var loginRequest = new LoginRequest
{
    Method = AuthenticationMethod.Anonymous.ToString(),
    Token = null,
};

var loginResponse = await sdk.LoginAsync(loginRequest).ConfigureAwait(false);

var getLocationsRequest = new GetLocationsRequest
{
    AccessToken = loginResponse.AccessToken,
    Protocol = Core.Model.Enums.Protocol.HydraTcp,
};

var getLocationsResponse = await sdk.GetLocationsAsync(getLocationsRequest).ConfigureAwait(false);
var selectedLocation = getLocationsResponse.VpnCustomLocations.FirstOrDefault();

var getCredentialsRequest = new GetCredentialsRequest
{
    AccessToken = loginResponse.AccessToken,
    VpnNode = selectedLocation,
    WithCertificate = true,
    Protocol = Core.Model.Enums.Protocol.HydraTcp,
};

var startVpnSessionRequest = new StartVpnSessionRequest()
{
    GetCredentialsRequest = getCredentialsRequest,
    EnableKillSwitch = false,
    EnableTunnelLogging = false,
    WaitConnected = true,
    AdapterName = "AdapterName",
};

var startVpnSessionResponse = await sdk.StartVpnSessionAsync(startVpnSessionRequest).ConfigureAwait(false);
if (startVpnSessionResponse.Result == ResponseResult.Ok)
{
    Console.WriteLine(startVpnSessionResponse.Message);
}

GetConnectionState

Gets current VPN connection state based on the VPN connection state stored in Unified SDK service.

var sdk = new SDK();
var stateResponse = await sdk.GetConnectionStateAsync().ConfigureAwait(false);
if (stateResponse.Result.Equals(ResponseResult.Ok))
{
    Console.WriteLine(stateResponse.OperationalState);
}

The VPN connection state represents an Enum:

• TunnelIdle - either doing nothing or trying to reconnect over and over again with no luck.

• TunnelConnecting - establishing the connection.

• TunnelConnected - connected to one or more servers and ready to process diverted network traffic.

• TunnelDisconnected - disconnected from all the connected servers (if any) and not diverting network traffic.

GetConnectedServerInfo

Returns the connected server information. It will be one of the servers received from GetCredentials response. Tunnel should be in the TunnelConnected state, otherwise it will return an error.

var sdk = new SDK();
var serverResponse = await sdk.GetConnectedServerInfoAsync().ConfigureAwait(false);
if (serverResponse.Result.Equals(ResponseResult.Ok))
{
    Console.Write(serverResponse.IPv4);
    Console.Write('-');
    Console.Write(serverResponse.Country);
    Console.Write('-');
    Console.WriteLine(serverResponse.Name);
}

StopVpn

Stops established VPN connection or cancel current connection/reconnection attempt.

var sdk = new SDK();
var stopVpnRequest = new StopVpnRequest
{
    KeepKillSwitchEnabled = false,
};
var stopVpnResponse = await sdk.StopVpnAsync(stopVpnRequest).ConfigureAwait(false);
Console.WriteLine(stopVpnResponse.ExitCode);