Authentication

The GraphQL API requires authentication for requests. Remote.It authentication uses HTTP Request Signature. The advantages of this method are:

Keys do not expire
Keys can be disabled and revoked (deleted) by the user at any time
Keys are not dependent on password
Keys are more secure (the secret is never transmitted because the request is signed)

With 2FA enabled, you'll need to provide an authentication code when accessing Remote.It through your browser, desktop and mobile apps. If you access Remote.It using other methods, such as the the CLI, you'll need to sign in with credentials using and access key and secret.

Key Management

You can generate, enable, disable and delete keys in the Account section of the web portal here https://app.remote.it/#/account/accessKey.

Please note: Generation of keys is crypto-random and the secret is only available immediately after creation by clicking the “Show secret access key” link or downloading the key as a CSV file (containing the Access Key ID and Secret Access Key)

You are limited to 2 active access keys. The account page will also show when the key was created and last used for authentication. If you suspect your key has been compromised, generate a new one, replace it in your code and disable it. If desired you can delete the compromised key after disabling it.

In addition, if you will be using the REST-API you will also need to retrieve your Developer API Key. This can also be found in the Account section of the web portal.

Create a remote.it Credentials File

You will need to follow the steps above with Key Management to generate your access key and secret before proceeding. Then, create a file to save your Remote.It credentials. The file name should be credentials with no extension. The folder depends on your operating system.

Operating System

Folder

Linux/macOS

~/.remoteit (in your home directory)

Windows

C:\Users\[your Windows user name]\.remoteit

The file is in the standard ini file format:

[DEFAULT]
R3_ACCESS_KEY_ID=Z5QCS6ZO7PXXXMVDNXXX
R3_SECRET_ACCESS_KEY=XXXWC14Qsktnq/nbF+iXxXq2yc4sVPkQn3J0m5i
R3_DEVELOPER_API_KEY=XXXXXXX

You can save more than one key pair under different profiles (sections) in the Remote.It credentials file. DEFAULT is the default profile name. Profiles name is case sensitive and should not have a "." in the name.

API Request Signing

Timezones

Request signing is done for each request independently and is sensitive to clock drift based on the system time of the machine making the API call.

Best practice is to use UTC or GMT when using the signature methods to avoid ambiguous time zones when dates are generated by your code.

To authenticate an API request, the client must generate a signature using the previously created key and secret. The REST-API example you will also need your Developer API Key which you can get from your account page https://app.remote.it/#account

Examples

These are examples of query requests only for the purposes of how to do the request signing. Please refer to the schema and usage documentation for requests which are supported.

The examples reads the ~/.remoteit/credentials file for the variables of your access key, secret, and developer key.

#!/bin/bash
source ~/.remoteit/credentials

SECRET=`echo ${R3_SECRET_ACCESS_KEY} | base64 --decode`

HOST="api.remote.it"
URL_PATH="graphql/v1"
URL="https://${HOST}/${URL_PATH}"

VERB="POST"

CONTENT_TYPE="application/json"

LC_VERB=`echo "${VERB}" | tr '[:upper:]' '[:lower:]'`

DATE=$(LANG=en_US date -u "+%a, %d %b %Y %H:%M:%S %Z")

DATA='{ "query": "{ login { email  devices (size: 1000, from: 0) { items { id name services { id name} } } } }" }'

SIGNING_STRING="(request-target): ${LC_VERB} /${URL_PATH}
host: ${HOST}
date: ${DATE}
content-type: ${CONTENT_TYPE}"

echo ${SIGNING_STRING}

SIGNATURE=`echo -n "${SIGNING_STRING}" | openssl dgst -binary -sha256 -hmac "${SECRET}" | base64`

SIGNATURE_HEADER="Signature keyId=\"${R3_ACCESS_KEY_ID}\",algorithm=\"hmac-sha256\",headers=\"(request-target) host date content-type\",signature=\"${SIGNATURE}\""

curl --write-out -v -X ${VERB} -H "Authorization:${SIGNATURE_HEADER}" -H "Date:${DATE}" -H "Content-Type:${CONTENT_TYPE}" ${URL} -d "${DATA}" --insecure

GraphQL

This typescript example shows

How to retrieve credentials from the remote.it credentials file using a default profile
Use http-signature client library to Authenticate each request
How to query GraphQL using variables and the https library

import fs from 'fs'
import https from 'https'
import os from 'os'
import path from 'path'

import httpSignature from 'http-signature'  // npm install http-signature
import ini from 'ini'                       // npm install ini

const R3_ACCESS_KEY_ID = 'R3_ACCESS_KEY_ID'
const R3_SECRET_ACCESS_KEY = 'R3_SECRET_ACCESS_KEY'

const CREDENTIALS_FILE = '.remoteit/credentials'
const DEFAULT_PROFILE = 'default'

const SIGNATURE_ALGORITHM = 'hmac-sha256'
const SIGNED_HEADERS = '(request-target) host date content-type'

const APPLICATION_JSON = 'application/json'

const GRAPHQL_HOST = 'api.remote.it'
const GRAPHQL_URL = '/graphql/v1'

function getCredentials(profileName = DEFAULT_PROFILE) {
  const file = path.resolve(os.homedir(), CREDENTIALS_FILE)

  if (!fs.existsSync(file)) throw new Error(`remote.it credentials file not found: ${file}`)

  const credentials = ini.parse(fs.readFileSync(file, 'utf-8'))

  const profile = Object.entries(credentials).find(([name]) => name.toUpperCase() === profileName.toUpperCase())

  if (!profile) throw new Error(`remote.it profile not found: ${profileName}`)

  const [_, section] = profile

  const keyId = section[R3_ACCESS_KEY_ID]

  if (!keyId) throw new Error(`remote.it credentials missing: ${R3_ACCESS_KEY_ID}`)

  const secret = section[R3_SECRET_ACCESS_KEY]

  if (!secret) throw new Error(`remote.it credentials missing: ${R3_SECRET_ACCESS_KEY}`)

  return {keyId, secret}
}

async function graphql(keyId, secret, query, variables) {
  const body = JSON.stringify({query, variables})

  const options = {
    host: GRAPHQL_HOST,
    port: 443,
    path: GRAPHQL_URL,
    method: 'POST',
    headers: {
      'Content-Type': APPLICATION_JSON
    },
    body
  }

  return new Promise((resolve, reject) => {
    const request = https.request(options, response => {
      response.on('data', json => resolve(JSON.parse(json)))
    })

    httpSignature.sign(request, {
      keyId,
      key: Buffer.from(secret, 'base64'),
      algorithm: SIGNATURE_ALGORITHM,
      headers: SIGNED_HEADERS.split(/\s+/)
    })

    request.on('error', error => reject(error))

    request.write(body)
    request.end()
  })
}

(async () => {
  try {
    const query = 'query TestQuery($id: String!) {' +
      '  login {' +
      '    device(id: [$id]) {' +
      '      name' +
      '      endpoint {' +
      '        timestamp' +
      '        state' +
      '        externalAddress' +
      '      }' +
      '    }' +
      '  }' +
      '}'

    const variables = {
      id: '80:00:00:00:01:02:03:04'
    }

    const {keyId, secret} = getCredentials()

    const result = await graphql(keyId, secret, query, variables)

    console.log(JSON.stringify(result, null, 2))
  } catch (error) {
    console.error(error)
  }
})()

This example is using a helper library requests_http_signature==v0.7.1 for Python 3 which will sign the request before submitting it to the server. This demonstrates how to safely reference the key and secret from the ~/.remoteit/credentials file.

Reference functions create a connection and have a disconnect.

import configparser
import json
import os.path
from base64 import b64decode

import requests
from requests_http_signature import HTTPSignatureAuth, algorithms

# File and URL Constants
CREDENTIALS_FILE = "~/.remoteit/credentials"
REMOTEIT_URL = 'https://api.remote.it/graphql/v1'


def remoteit_authorizer(profile="DEFAULT"):
    """Authorize remote.it API access using credentials from a file.

    Args:
        profile (str, optional): Profile name in credentials file. Defaults to "DEFAULT".

    Returns:
        HTTPSignatureAuth: Auth object to be used in requests.
    """
    # Resolve the full path for the credentials file
    file = os.path.expanduser(CREDENTIALS_FILE)

    # Check if the file exists
    if not os.path.exists(file):
        raise FileNotFoundError(f"remote.it credentials file not found: {file}")

    # Parse the credentials file
    config = configparser.ConfigParser()
    try:
        config.read(file)
    except Exception as e:
        raise Exception(f"remote.it credentials file error: {e}")

    # Fetch credentials for the selected profile
    credentials = config[profile]

    # Validate existence of required keys
    key_id = credentials.get('R3_ACCESS_KEY_ID')
    key = credentials.get('R3_SECRET_ACCESS_KEY')
    if not key_id or not key:
        raise Exception("Missing required credentials")

    # Create and return auth object
    return HTTPSignatureAuth(key_id=key_id, key=b64decode(key), signature_algorithm=algorithms.HMAC_SHA256)


def remoteit_api(auth, query, variables=None):
    """Send a GraphQL query to remote.it API.

    Args:
        auth (HTTPSignatureAuth): Auth object.
        query (str): GraphQL query string.
        variables (dict, optional): Variables for the GraphQL query. Defaults to None.

    Returns:
        dict: Parsed JSON response from the API.
    """
    response = requests.post(REMOTEIT_URL, json={"query": query, "variables": variables}, auth=auth)
    if response.status_code != 200:
        raise Exception(f"remote.it API error: {response.status_code}")
    return json.loads(response.text)


def connect(auth, service_id):
    """Connect to a remote.it service and return session details.

    Args:
        auth (HTTPSignatureAuth): Auth object.
        service_id (str): The service ID.

    Returns:
        tuple: Session ID, host, and port.
    """
    query = "mutation connect($id: String!) {connect(serviceId: $id) {id host port}}"
    response = remoteit_api(auth, query, variables={"id": service_id})
    connection = response["data"]["connect"]
    return connection["id"], connection["host"], connection["port"]


def disconnect(auth, session_id):
    """Disconnect a remote.it session.

    Args:
        auth (HTTPSignatureAuth): Auth object.
        session_id (str): The session ID to disconnect.

    Returns:
        bool: True if successful, False otherwise.
    """
    query = "mutation disconnect($id: String!) {disconnect(connectionId: $id)}"
    response = remoteit_api(auth, query, variables={"id": session_id})
    return response["data"]["disconnect"]


# Example usage
if __name__ == "__main__":
    # Initialize authorizer
    authorizer = remoteit_authorizer()

    # Connect to a service
    service_id = "80:XX:XX:XX:XX:XX:XX:XX"
    session_id, host, port = connect(authorizer, service_id)
    print(f"Connected: session_id={session_id}, host={host}, port={port}")

    # Disconnect from the service
    status = disconnect(authorizer, session_id)
    print(f"Disconnected: {status}")

This example is using RestSharp to make the requests, and the built in cryptography library (System.Security.Cryptography) to sign the request. This demonstrates using a configuration manager to safely reference the key and secret from environmental variables rather than including it in the code. You will need to set the environmental variables before executing.

ExecuteRequest requires a string which is your graphQL query body.

graphQL

private static readonly RestClient Client = new RestClient("https://api.remote.it/graphql/v1");
private static readonly HMACSHA256 SignatureGenerator = new HMACSHA256(Convert.FromBase64String(ConfigurationManager.AppSettings.Get("R3_SECRET_ACCESS_KEY")));

public static async Task<IRestResponse> ExecuteRequest(string requestContent)
{
    string date = DateTime.UtcNow.ToString("ddd, dd MMM yyy HH':'mm':'ss 'GMT'");

    string signatureParams = "(request-target): post /graphql/v1\n" +
    "host: api.remote.it\n" +
    $"date: {date}\n" +
    "content-type: application/json\n"";
    string signature = Convert.ToBase64String(SignatureGenerator.ComputeHash(Encoding.UTF8.GetBytes(signatureParams)));

    RestRequest request = new RestRequest(Method.POST);
    request.AddHeader("Host", "api.remote.it");
    request.AddHeader("Date", date);
    request.AddHeader("Content-Type", "application/json");
    request.AddHeader("Authorization", 
        $"Signature keyId=\"{ConfigurationManager.AppSettings.Get("R3_ACCESS_KEY_ID")}\"," +
            "algorithm=\"hmac-sha256\"," +
            "headers=\"(request-target) host date content-type\"," +
            $"signature=\"{signature}\"");
    request.AddParameter("application/json", requestContent, ParameterType.RequestBody);

    var response = await Client.ExecuteAsync(request);
    return response;
}

PreviousOrganizations NextAPI

Last updated 6 months ago