Note

You are viewing the legacy Cascade documentation, which only applies to some Rigado customers. To view the current Cascade documentation, click here.

2.4. 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 accept 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 example purposes, this document will use the token EXAMPLE_TOKEN_Rngdskog4u3u9nvdl and the secret EXAMPLE_SECRET_dasdioansrksafnasd.

Warning

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 multitenant system, choose user environment variables instead of system environment variables.

2.4.1. 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  EXAMPLE_TOKEN_Rngdskog4u3u9nvdl  EXAMPLE_SECRET_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.

2.4.2. 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 EXAMPLE_TOKEN_Rngdskog4u3u9nvdl --apisecret EXAMPLE_SECRET_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: EXAMPLE_TOKEN_Rngdskog4u3u9nvdl" -H "X-Rigado-API-Secret: EXAMPLE_SECRET_dasdioansrksafnasd" https://api.rigado.com/v1/gateways
...

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

2.4.3. Example: Uploading a new app revision using the CLI

To upload and release a new revision of your app, use the app upload command.

This example uploads myApp_1.0.0_armhf.snap as a new revision to myApp, and releases that revision to the edge and beta channels, all using an API key.

$ rigado app upload myApp --filename myApp_1.0.0_armhf.snap --channel edge,beta --apisecret EXAMPLE_SECRET_dasdioansrksafnasd --apitoken EXAMPLE_TOKEN_Rngdskog4u3u9nvdl

Note

Edge Direct doesn’t support direct API interaction by external clients for uploading revisions, due to the complexity of the request exchanges. App revision uploads and releases must be handled through the CLI.

2.4.4. Other examples of using an API key

Below are some additional 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 EXAMPLE_SECRET_dasdioansrksafnasd --apitoken EXAMPLE_TOKEN_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
...

Fetch metrics from a gateway

Note

The CLI does not currently support fetching gateway metrics from Edge Direct.

$ 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/metrics
...

List all tags

$ rigado tag list --apisecret EXAMPLE_SECRET_dasdioansrksafnasd --apitoken EXAMPLE_TOKEN_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
...

Add a tag to a gateway

$ rigado gateway add-tag C017013717-00134 --key TAG_KEY --value TAG_VALUE --apisecret EXAMPLE_SECRET_dasdioansrksafnasd --apitoken EXAMPLE_TOKEN_Rngdskog4u3u9nvdl
...
$ curl -X POST -H "X-Rigado-API-Token: EXAMPLE_TOKEN_Rngdskog4u3u9nvdl" -H "X-Rigado-API-Secret: EXAMPLE_SECRET_dasdioansrksafnasd" https://api.rigado.com/v1/gateways/C017013717-00134/tags -d '{"tag":"TAG_NAME", "value":"TAG_VALUE"}'
...

Remove a tag from a gateway

$ rigado gateway remove-tag SERIAL_NUMBER --key TAG_KEY --apisecret EXAMPLE_SECRET_dasdioansrksafnasd --apitoken EXAMPLE_TOKEN_Rngdskog4u3u9nvdl
...
$ curl -X DELETE -H "X-Rigado-API-Token: EXAMPLE_TOKEN_Rngdskog4u3u9nvdl" -H "X-Rigado-API-Secret: EXAMPLE_SECRET_dasdioansrksafnasd" https://api.rigado.com/v1/gateways/C017013717-00134/tags/TAG_NAME
...

List bundles

$ rigado bundle list --apisecret EXAMPLE_SECRET_dasdioansrksafnasd --apitoken EXAMPLE_TOKEN_Rngdskog4u3u9nvdl
  NAME      TAGS  APPS  DESCRIPTION
  default
$ 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/bundles
...

Release an existing revision to a new channel

$ rigado app release APP_NAME --revision REVISION --channel CHANNEL --apisecret EXAMPLE_SECRET_dasdioansrksafnasd --apitoken EXAMPLE_TOKEN_Rngdskog4u3u9nvdl
...
$ curl -X POST -H "X-Rigado-API-Token: EXAMPLE_TOKEN_Rngdskog4u3u9nvdl" -H "X-Rigado-API-Secret: EXAMPLE_SECRET_dasdioansrksafnasd" https://api.rigado.com/v1/apps/APP_NAME/revisions/REVISION -d '{"name":"APP_NAME", "revision":"REVISION"}'
...

Note

You are viewing the legacy Cascade documentation, which only applies to some Rigado customers. To view the current Cascade documentation, click here.