Connecting to a Service using the API

post
Connect to a device

https://api.remot3.it/apv/v27/device/connect
Create a connection to a device. Please note that the term "device" in this context is a legacy reference. In all other contexts on this web site, a "device" is called a "Service".
Request
Response
Request
Headers
developerkey
required
string
Your developer key which can be found by logging into remote.it and going to your "Account" settings page.
token
required
string
Your session token, created by logging in using the API.
Body Parameters
deviceaddress
required
string
The service address (e.g. service ID) for the device you'd like to connect to
wait
required
boolean
Whether to wait for the connection or not. Should be set to "true"
hostip
required
string
Controls the connection mode. See description below.
Response
200: OK
Connection with device successfully created.
{
"connection": {
"deviceaddress": "80:00:00:00:00:00:00:91",
"expirationsec": "28797",
"proxy": "https://xppoobalo.p18.rt3.io"
"connectionid":"A78B3919-52E1-B674-58CC-5C0009377419"
},
"status": "true"
}

For http and https remote.it Services, the returned value for "proxy" will be a single string similar to the following. It does not need an explicit port value to be used. These are "reverse proxies". Reverse proxies are always public, which is why the randomized URL is generated at the time of creating the connection.

"proxy": "https://xprbjalo.p18.rt3.io"

For all other types of remote.it Services, the returned value for "proxy" will include a hostname and a port value separated by a colon, as shown below. These are "port proxies".

"proxy": "http:\/\/proxy18.rt3.io:38575"

Connection modes

The following options apply only to "port proxies", namely all Service types except the http and https Service types, which use "reverse proxies". Reverse proxies are always public which is why the randomized URL is created.

Public

By setting the "hostip" parameter to 0.0.0.0, anyone who has the connection URL and port can connect to it until the connection expires or is closed using the API described at Terminating a proxy connection to a device. If you use the Public connection mode, make sure that your resources are properly password protected.

IP Restricted

By setting the "hostip" parameter to the client's public IP address, IP restriction is enabled. Only connections coming from that public IP address will be allowed. Any other incoming connection will be blocked.

IP Latching

By setting the "hostip" parameter to 255.255.255.255, whoever uses the connection URL and port first will "latch" the connection, blocking all other connection attempts regardless of where they originated.

The value returned for "connectionid" can be used with the /device/connect/stop API endpoint to terminate the proxy connection to your target when you are done using it.

Note Some response values are omitted from the example above because they are only used in very specific circumstances.

Usage Examples

cURL
Node (JavaScript)
Python
C#
PHP
cURL
#!/bin/sh
TOKEN="your_login_token"
DEV_KEY="your_developer_key"
DEVICE_ADDRESS="your_service_id"
HOSTIP="your_public_ip"
curl -X POST \
-H "token:$TOKEN" \
-H "developerkey:$DEV_KEY" \
-d "{\"wait\":\"true\",\"deviceaddress\":\"$DEVICE_ADDRESS\", \
\"hostip\":\"$HOSTIP\" }" \
https://api.remot3.it/apv/v27/device/connect
Node (JavaScript)
const axios = require("axios");
const developerkey = process.env.REMOTEIT_DEVELOPER_KEY;
const token = process.env.REMOTEIT_TOKEN;
const deviceaddress = process.env.REMOTEIT_DEVICE_ADDRESS;
const hostip = process.env.MY_PUBLIC_IP;
const wait = "true";
axios
.post(
"https://api.remot3.it/apv/v27/device/connect",
{
deviceaddress,
wait,
hostip
},
{
headers: {
developerkey,
token
}
}
)
.then(response => {
console.log("Status Code:", response.status);
console.log("Body:", response.data);
})
.catch(error => {
console.log(error);
});
Python
import requests
import json
import os
headers = {
"developerkey": os.environ["REMOTEIT_DEVELOPER_KEY"],
# Created using the login API
"token": os.environ["REMOTEIT_TOKEN"]
}
body = {
"deviceaddress": "80:00:00:3F:AE:00:00:11",
"wait":"true",
"hostip":os.environ["MY_PUBLIC_IP"]
}
url = "https://api.remot3.it/apv/v27/device/connect"
response = requests.post(url, data=json.dumps(body), headers=headers)
response_body = response.json()
print("Status Code: %s" % response.status_code)
print("Raw Response: %s" % response.raw)
print("Body: %s" % response_body)
C#
using System;
using System.Net.Http;
using Newtonsoft.Json;
using System.Collections.Generic;
namespace remote.it_api_example
{
class Program
{
static void Main(string[] args)
{
string jsonString = "";
string url = "https://api.remot3.it/apv/v27/device/connect";
HttpClient client = new HttpClient();
HttpRequestMessage requestData = new HttpRequestMessage();
// Configure the HTTP requests's url, headers, and body
requestData.Method = HttpMethod.Post;
requestData.RequestUri = new Uri(url);
requestData.Headers.Add("developerkey", Environment.GetEnvironmentVariable("REMOTEIT_DEVELOPER_KEY"));
requestData.Headers.Add("token", Environment.GetEnvironmentVariable("REMOTEIT_TOKEN"));
Dictionary<string, string> bodyData = new Dictionary<string, string>() {
{
"deviceaddress", Environment.GetEnvironmentVariable("REMOTEIT_DEVICE_ADDRESS"),
"wait", "true",
"hostip", Environment.GetEnvironmentVariable["MY_PUBLIC_IP"]
}
};
string jsonFormattedBody = JsonConvert.SerializeObject(bodyData);
requestData.Content = new StringContent(jsonFormattedBody);
try
{
// Send the HTTP request and run the inner block upon recieveing a response
var response = client.SendAsync(requestData).ContinueWith((taskMessage) =>
{
var result = taskMessage.Result;
var jsonTask = result.Content.ReadAsStringAsync();
jsonTask.Wait();
// Store the body of API response
jsonString = jsonTask.Result;
});
response.Wait();
}
catch (HttpRequestException e)
{
// Triggered when the API returns a non-200 response code
jsonString = e.Message;
}
// Print JSON response from API
Console.WriteLine(jsonString);
}
}
}
PHP
<?php
$ch = curl_init();
curl_setopt_array($ch, array(
CURLOPT_URL => "https://api.remot3.it/apv/v27/device/connect",
CURLOPT_HTTPHEADER => array(
"developerkey: ".$_ENV["REMOTEIT_DEVELOPER_KEY"],
"token: ".$_ENV["REMOTEIT_TOKEN"] // Created using the login API
),
CURLOPT_POSTFIELDS => json_encode(array(
"deviceaddress" => $_ENV["REMOTEIT_DEVICE_ADDRESS"],
"wait" => true,
"hostip" => $_ENV["MY_PUBLIC_IP"]
)),
CURLOPT_RETURNTRANSFER => true
));
$response = curl_exec($ch);
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
print("Status Code: ".$statusCode."\n");
$responseData = json_decode($response);
print_r($responseData);
?>