Overview

This guide will introduce you to creating, managing, and deleting API keys within the Edge Direct web-based application, or via the rigado CLI, as well as using API keys to authenticate with the Edge Direct API.

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

Using this authentication method enables users to interact with the API in various 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 and displays it to the end user.

All rigado CLI 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 has 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.

Creating, Managing, and Deleting API keys in Edge Direct

Creating API Keys in Edge Direct

Once logged into Edge Direct,

1. Click on User Management
2. Click on API Keys
3. Click on 'create API key'

1. Select an API Key Role

• Edge Direct offers four API Key Roles, each granting different levels of privileges:
  • Administrator – Full access to all Edge Direct features, global settings, and Sites. Administrator is the only role that can manage user access and roles.
  • Site Owner – Full Read/Write access to all features within assigned Sites, without visibility into unassigned Sites.
  • Site Watcher – Read-only access to selected Sites, allowing visibility into Site health and configurations without the ability to make changes.
  • Installer – Full Read and limited Write access to selected Sites for installation and provisioning, restricted to network and site-specific configurations.
  • API Key Roles are based on User Roles. For a full breakdown of their capabilities, see User Roles

2. Enter a Note (Optional)

• This field is user-configurable. You can use it to add a tag or description for the API key’s purpose.
• This is the only field that can be changed after key creation.

3. Set an Expiration Date (Optional)

• You may specify an expiration date or leave it blank for a non-expiring key.
• Follow your organization's security policies for recommended expiration guidelines.

4. Enable New Site Access (Optional)

• For non-administrator roles, you can enable automatic access to newly created Sites.
• Without selecting this, all non-administrator roles will only have access to the Sites specified. This cannot be changed after creation.

5. Define Site Access

• Choose whether the API key has access to all Sites or a specific set of existing Sites. This cannot be changed after creation.

6. Click Submit

7. Copy and save the API token and secret in a secure location
   The API Key token and secret will be available to copy. Clicking on the blue box at the right of each line will copy the entire string automatically. Once you navigate away from this page, you will never be able to access the API secret again.

   

❗️

API Key Secret

The initial creation screen is the only time users can access the API Key Secret. Users should store this key in a secure location for future use. Without the API Key Secret this key will be unusable.

Managing API Keys in Edge Direct

A list of all API keys for your organization, along with the optional note and creation date can be found by in Edge Direct

1. Click on User Management
2. Click on API Keys

API Key Details, including Sites Accessible, can be found by clicking anywhere on an API Key's row.

The only field that is editable after API Key initial creation is Note. This field is purely for user reference and has no impact on Key permissions or functionality. All other information provided in this view, such as Role, Sites Accessible, and Token are read only for user reference.

Deleting API keys in Edge Direct

Once inside the API Key Details pane for the key to be deleted, click the Delete button in the top right.

This will bring up a confirmation window, click the Delete Key button to confirm deletion.

Creating, Managing, and Deleting API keys via Rigado CLI

Creating API Keys via Rigado CLI

The command below, and optional flags allow you to generate a new API Key with specific role-based permissions, optional site access restrictions, and an expiration date.

   $ rigado apikey create [flags]

Options

      --all-sites           Access to all sites (true/false)
      --expiration string   The date (YYYY-MM-DD) which the key will expire midnight UTC
  -h, --help                help for create
      --new-sites           Access to newly created sites (true/false)
      --no-prompt           Suppresses input prompts
      --note string         A note or other information pertaining to the key
      --role string         The role and permissions the key will be scoped to (default "Administrator")
      --sites string        Access to specific sites in organization for the key, listed by site names and separated by a commad

Options Explained

1. Define Site Access
   • Choose whether the API key has access to all Sites or a specific set of existing Sites. This cannot be changed after creation.
2. Set an Expiration Date (Optional)
   • You may specify an expiration date or leave it blank for a non-expiring key.
   • Follow your organization's security policies for recommended expiration guidelines.
3. Enable New Site Access (Optional)
   • For non-administrator roles, you can enable automatic access to newly created Sites.
   • Without selecting this, all non-administrator roles will only have access to the Sites specified. This cannot be changed after creation.
4. Enter a Note (Optional)
   • This field is user-configurable. You can use it to add a tag or description for the API key’s purpose.
   • This is the only field that can be changed after key creation.
5. Enter an API Key Role
   • Edge Direct offers four API Key Roles, each granting different levels of privileges:
     • Administrator – Full access to all Edge Direct features, global settings, and Sites. Administrator is the only role that can manage user access and roles.
     • Site Owner – Full Read/Write access to all features within assigned Sites, without visibility into unassigned Sites.
     • Site Watcher – Read-only access to selected Sites, allowing visibility into Site health and configurations without the ability to make changes.
     • Installer – Full Read and limited Write access to selected Sites for installation and provisioning, restricted to network and site-specific configurations.
     • API Key Roles are based on User Roles. For a full breakdown of their capabilities, see User Roles
6. Define Site Access (Optional)
   • List specific sites in organization the key should have access to, listed by site names and separated by a comma. This cannot be changed after creation.
7. Press enter to Confirm
8. Copy and save the API token and secret in a secure location
   The API Key token and secret will be available to copy.

❗️

API Key Secret

The creation message is the only time users can access the API Key Secret. Users should store this key in a secure location for future use. Without the API Key Secret this key will be unusable.

Managing API Keys via Rigado CLI

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.

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

Deleting API Keys via Rigado CLI

The rigado apikey delete API_KEY_TOKEN command deletes the key.

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