Fetching endpoints for a location

Endpoints represent a specific configuration for a protocol running on a VPN server. They contain all required configuration parameters for the VPN connection to be setup.

Protocol Pecking Order

Endpoints returned by the SDK are consistently organized based on the Protocol Pecking Order established by the Ops team. This order specifies the preferred protocol combinations and parameters that an application should utilize to establish a connection.

For platforms that support parallel connections, the SDK will initiate connections to all instances simultaneously. The connection that succeeds with the lowest index will be designated as the "winner" and will be used for the VPN session.

get_instances_for_protocols

Fetch endpoints for the specified location over HTTP call or read from cache, small response payload of a few kilobytes. The protocol, pecking order is applied on the backend. A shortcut to this method is get_endpoints() which will set the protocol filter to lightway, openvpn and wireguard .

The protocols argument can specify exact protocol as specified by user preferences, or full list of protocols supported by current client after which the client can filter protocol according to user preferences.

Parameters

Name	Type	Description
subscription_id	String	ID of the subscription which has a VPN entitlement. You can obtain that subscription id as described in Obtaining a VPN Subscription ID
location_id	String	Unique ID of the location obtained from the get_locations_for_protocols() method
protocols	Array of InstanceProtocol	List of protocols as specified by user preferences, or a full list of protocols supported by current client. lightway openvpn wireguard proxy

Returns

LocationEndpoints upon success, InstanceDiscoveryException otherwise.

get_endpoints_for_protocols

Read the full dataset from local cache, find requested location and protocols, apply pecking order on the client side. If the local cache is empty or outdated then return an error. Because of the size of full dataset cache, over 3MB JSON, this method requires at least 10MB of heap.

To update the cache, a call to get_full_locations_for_protocols() has to be executed first.

The protocols argument can specify exact protocol as specified by user preferences, or full list of protocols supported by current client after which the client can filter protocol according to user preferences.

Parameters

Name	Type	Description
subscription_id	String	ID of the subscription which has a VPN entitlement. You can obtain that subscription id as described in Obtaining a VPN Subscription ID
location_id	String	Unique ID of the location obtained from the get_locations_for_protocols() method
protocols	Array of InstanceProtocol	List of protocols as specified by user preferences, or a full list of protocols supported by current client. lightway openvpn wireguard proxy

Returns

LocationEndpoints upon success, InstanceDiscoveryException otherwise.

LocationEndpoints

Name	Type	Description
location_id	String	ID of the location this instances belongs to
endpoints	Array of EndpointConfigurations	See EndpointConfiguration

EndPointConfiguration

And endpoint configuration can be one of the following types

EndpointConfiguration.lightway

Name	Type	Description
ip	IPAddress	IP address of the endpoint
port	Integer	Port of the endpoint
transport	ProtocolTransport	Either udp or tcp
mtu	Integer	Maximum Transmission Unit
certDn	String	Expected Certificate's CN value for that server
obfuscation	LightwayObfuscation	Lightway Obfuscation Method to be used None, FM1 { fm1_input: String, fm_server: String, }, FM2 { fm2_input: String, fm_server: String, }

EndpointConfiguration.openVpn

Name	Type	Description
ip	IPAddress	IP address of the endpoint
port	Integer	Port of the endpoint
transport	ProtocolTransport	Either udp or tcp
mtu	Integer	Maximum Transmission Unit
certDn	String	Expected Certificate's CN value for that server
ovpnConfiguration	String	OpenVPN Configuration Parameters
ovpnConfigTemplate	(Optional) String	OpenVPN Configuration Template
xorValue	Integer	XOR Value for OpenVPN Obfuscation

EndpointConfiguration.wireGuard

WireGuard will always use the udp transport type. WireGuard requires a Public/Private keypair to be generated for each new connection and the public key to be send to the endpoint's authentication IP and port to be registered. The SDK will automatically handle this, if a WireGuard Session Token for a specific endpoint is fetched.

Name	Type	Description
ip	IPAddress	IP address of the endpoint
port	Integer	Port of the endpoint
authIP	IpAddress	IP of the authentication endpoint
authPort	Integer	IP of the authentication port
certDn	String	Expected Certificate's CN value for that server
obfuscation	WireGuardObfuscation	Type of WireGuard Obfuscation to be used None, Amnezia { s1: u64, s2: u64, jc: u64, jmin: u64, jmax: u64, h1: u64, h2: u64, h3: u64, h4: u64, }

EndpointConfiguration.httpProxy

This configuration represents and HTTP(s) Proxy which can be used in browser extensions. It will only return the hostname of the proxy to use.

IPAddress

This represents either an v4 or v6 IP Address.