API Authentication
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
Updated 24 days ago