Authenticating with API Keys

This guide will introduce you to using an API token and secret to authenticate with the Edge Direct API.

The Edge Direct API allows a user to authenticate their calls with an API token and an API secret---a pair of values known collectively as an API key.

This method enables users to interact with the API in new ways. For example:

• A continuous integration / continuous delivery mechanism that builds your app and uploads it to your organization.
• A script that runs every day, checking Gateway metrics and saving Gateway logs.
• A smartphone application that fetches information from Edge Direct, then displays that information for the end-user.

All rigado command calls support the use of an API key. Also, calls to the Edge Direct API using utilities such as curl may use an API key through custom HTTP headers.

API tokens always start with RT_ and always end with =. Likewise, API secrets always start with RS_ and end with =. For demonstration, this document will use the token RT_EXAMPLE_Rngdskog4u3u9nvdl= and the secret RS_EXAMPLE_dasdioansrksafnasd=.

🚧

API Key Safety

We recommend you observe these precautions when using and storing API
keys:

• Don't embed API keys directly into code, and don't commit API keys
  into any version-control system (e.g. git, svn).
• Don't run commands on a shared machine that have API keys hardcoded
  into the command. Many shell terminals will save commands in a
  history file.
• Pass API keys via environment variables. On a multi-tenant system,
  choose user environment variables instead of system environment
  variables.

Getting an API key

Use the CLI to create, manage, and delete API keys.

$ rigado apikey create
Loaded credentials from '/home/myuser/.rigado/EdgeDirect.RefreshToken'
  CREATED               TOKEN                             SECRET
  2018-09-10T08:18:17Z  RT_EXAMPLE_Rngdskog4u3u9nvdl=  RS_EXAMPLE_dasdioansrksafnasd=

The rigado apikey list command lists all API keys for your organization.

The rigado apikey info API_KEY_TOKEN command will show information about a single API key, including its secret.

More information about the apikey command can be found in the CLI
documentation.

Using an API key

Using a key with the Edge Direct CLI

Any rigado CLI command can use an API key for authentication.

After you get an API key you can use it by providing the arguments --apisecret and --apitoken.

--apisecret string   API Secret for authentication (instead of user-based auth)
--apitoken string    API Token for authentication (instead of user-based auth)

In the following example we use an API key to list Gateways:

$ rigado gateway list --apitoken RT_EXAMPLE_Rngdskog4u3u9nvdl= --apisecret RS_EXAMPLE_dasdioansrksafnasd=
...

Using a key with the Edge Direct API

HTTP calls directly to the Edge Direct API can also use an API key for authentication.

After you get an API key using the CLI, you can use it in an HTTP call by providing the headers X-Rigado-API-Token and X-Rigado-API-Secret in your request.

In the following example we use an API key to list Gateways:

$ curl -H "X-Rigado-API-Token: RT_EXAMPLE_Rngdskog4u3u9nvdl=" -H "X-Rigado-API-Secret: RS_EXAMPLE_dasdioansrksafnasd=" https://api.rigado.com/v1/gateways
...

For more information about the endpoints available for direct HTTP calls, see the Edge Direct API Reference

Examples of using an API key

Below are some examples of using API keys for authentication with Edge Direct.

Fetch logs from a Gateway

rigado gateway logs C017013717-00134 --duration lastHour --unit snap.rigado-node-hello-world.thingy-hello-world.service --apisecret RS_EXAMPLE_dasdioansrksafnasd= --apitoken RT_EXAMPLE_Rngdskog4u3u9nvdl=
Requesting logs....
Log file written to C031031821-00053_2018-09-07T16:20:32Z.gz

 curl -H "X-Rigado-API-Token: EXAMPLE_TOKEN_Rngdskog4u3u9nvdl" -H "X-Rigado-API-Secret: EXAMPLE_SECRET_dasdioansrksafnasd" https://api.rigado.com/v1/gateways/C017013717-00134/logs/1d23c456-f782-9a6c-9105-29c61eee8ab4

List all tags

rigado tag list --apisecret RS_EXAMPLE_dasdioansrksafnasd= --apitoken RT_EXAMPLE_Rngdskog4u3u9nvdl=
  TAG
  location
  customer

curl -H "X-Rigado-API-Token: EXAMPLE_TOKEN_Rngdskog4u3u9nvdl" -H "X-Rigado-API-Secret: EXAMPLE_SECRET_dasdioansrksafnasd" https://api.rigado.com/v1/tags