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)

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.

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

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

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

Last updated

Was this helpful?