Skip to content

Instantly share code, notes, and snippets.

@Netkas

Netkas/openblu_api_v1iva2.0.md

Last active February 5, 2021 12:51
Show Gist options
  • Save Netkas/6d09bd76ad8a6eaee6a6229b17eb373f to your computer and use it in GitHub Desktop.
Save Netkas/6d09bd76ad8a6eaee6a6229b17eb373f to your computer and use it in GitHub Desktop.
Download ZIP
OpenBlu API Documentation for IVA2.0
Raw
openblu_api_v1iva2.0.md

Notice! This documentation is outdated & will no longer be updated.

We've recently moved to https://docs.intellivoid.net/openblu/introduction

OpenBlu API V1-IVA2.0

This document explains how to use the OpenBlu API to retrieve OpenBlu servers, filter them and retrieve their OpenVPN configuration details

Authenticate

OpenBlu API uses Intellivoid API, to learn how to authenticate each request see intellivoid_api_authentication.md which goes into details on how to authenticate.

What's this?

OpenBlu API is a Application Programming Interface for OpenBlu which allows you to retrieve OpenVPN servers and the details about those servers to allow you to connect using a generic OpenVPN client.

API Methods

Method Name Access URI Request Methods Description
list_servers https://api.intellivoid.net/openblu/v1/servers/list GET POST Retrieves all the available servers from OpenBlu
get_server https://api.intellivoid.net/openblu/v1/servers/get GET POST Gets the details of an existing server by the server ID

List Servers

This method allows you to retrieve OpenVPN servers that are available on OpenBlu, this method allows you to filter and order the results in different ways. These results do not return the actual details about each server, you need to use the Get Server method to accomplish that.

Parameters

Parameter Name Default Value Required Description
filter None No Filters the results by country or country_short
by None Yes (If filter is used) The value to filter by, eg; japan, thailand, etc.
order_by last_updated No Orders the results by score, ping, sessions, total_sessions, last_updated and created
sort_by descending No Sorts the ordered results by descending or ascending

Example Results

{
  "success": true,
  "response_code": 200,
  "servers": [
    {
      "id": "8cd76121cb412234",
      "host_name": "vpn449395045",
      "country": "Thailand",
      "country_short": "TH",
      "score": 577616,
      "ping": 30,
      "sessions": 61,
      "total_sessions": 34133,
      "last_updated": 1580340394,
      "created": 1580340394
    },
    {
      "id": "563eb9182ba28749",
      "host_name": "vpn336227155",
      "country": "Thailand",
      "country_short": "TH",
      "score": 520198,
      "ping": 38,
      "sessions": 13,
      "total_sessions": 2302,
      "last_updated": 1580340394,
      "created": 1580340394
    },
    {
      "id": "58c61a8d1f8ec36b",
      "host_name": "vpn589223849",
      "country": "Thailand",
      "country_short": "TH",
      "score": 615902,
      "ping": 27,
      "sessions": 50,
      "total_sessions": 27778,
      "last_updated": 1580070319,
      "created": 1580070319
    },
    {
      "id": "f3eba00c4efe51a9",
      "host_name": "vpn543929979",
      "country": "Thailand",
      "country_short": "TH",
      "score": 571883,
      "ping": 25,
      "sessions": 0,
      "total_sessions": 3226,
      "last_updated": 1580070319,
      "created": 1580070319
    }
  ]
}

Server Listing Structure

Name Type Description
id string The ID of the server
host_name string The name of the host of the server
country string The full name of the country that this server is based in
country_short string The short version of the country that this server is based in
score int The score of the server
ping int The ping of the server
sessions int The amount of sessions that are currently established to this server
total_sessions int The total amount of sessions that has been established
last_updated int The Unix Timestamp of when this server was last updated
created int The Unix Timestamp of when this server was created

No Results

No errors will be shown if no results are returned

{
  "success": true,
  "response_code": 200,
  "servers": []
}

Get Server

This method allows you to get an existing server from OpenBlu. This includes the certificate, connection parameters, IP address and more.

Parameters

Parameter Name Default Value Required Description
id None Yes The ID of the VPN Server

Example Results

Some of the data is replaced with <> to simplify the contents

{ 
   "success":true,
   "response_code":200,
   "server":{ 
      "id":"ffd07d9e2adf70ef",
      "host_name":"vpn853872483",
      "country":"Japan",
      "country_short":"JP",
      "score":398502,
      "ping":1,
      "sessions":47,
      "total_sessions":417240,
      "ip_address":"103.201.129.18",
      "openvpn":{ 
         "parameters":{ 
            "dev":"tun",
            "proto":"tcp",
            "remote":"103.201.129.18 443",
            "cipher":"AES-128-CBC",
            "auth":"SHA1",
            "resolv-retry":"infinite",
            "nobind":null,
            "persist-key":null,
            "persist-tun":null,
            "client":null,
            "verb":"3"
         },
         "certificate_authority":"<CERTIFICATE DATA>",
         "certificate_authority_b64":"<BASE64 ENCODED CERTIFICATE DATA>",
         "certificate":"<CERTIFICATE DATA>",
         "certificate_b64":"<BASE64 ENCODED CERTIFICATE DATA>",
         "key":"<PRIVATE KEY DATA>",
         "key_b64":"<BASE64 PRIVATE KEY DATA>",
         "ovpn_configuration":"<.OVPN FILE CONTENTS>"
      },
      "last_updated":1580340394,
      "created":1580070319
   }
}

Server Object Structure

Name Type Description
id string The ID of the VPN Server
host_name string The name of the host of the server
country string The name of the country that this server is based in
country_short string The short version of the country name
score int The score of the VPN server
ping int The ping of the server
sessions int The amount of sessions that are on the server now
total_sessions int The total amount of sessions established to this server overtime
ip_address string IPV4/IPV6 Address of the server
openvpn openvpn The OpenVPN details for connecting to this server
last_updated int The Unix Timestamp of when this server was last updated
created int The Unix Timestamp of when this server was created

OpenVPN Object Structure

Name Type Description
parameters array (key:string)/(key:null) The parameters for a OpenVPN Client to use, null values means that the parameter does not require a value
certificate_authority string The certificate authority of for the VPN Server
certificate_authority_b64 string (Base64 Encoded) The same as certificate_authority but with the contents base64 encoded
certificate string The certificate of the VPN Server
certificate_b64 string (Base64 Encoded) The same as certificate but with the contents base64 encoded
key string Private RSA Key for the VPN Server
key_b64 string (Base64 Encoded) The same as key but with the contents base64 encoded
ovpn_configuration string The full contents of the .ovpn file including all the certificates and parameters to connect

Server not Found

This response is given when the given ID does not point to any existing server that is registered in OpenBlu

{
  "success": false,
  "response_code": 404,
  "error": {
    "error_code": 0,
    "type": "CLIENT",
    "message": "VPN Server not found"
  }
}

This documentation was written with ❤️ by netkas

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment