Generate an APIKey in Aura

Introduction

All Aura’s public APIs are protected using an APIKey.

The generation of an APIKey can be done using two alternative processes:

• Generate an APIKey from Aura installer aurak8s
  Follow the instructions in the document Create Aura APIKeys

• Generate an APIKey using the aura-api-key-generator utility

  • aura-api-key-generator is an Aura utility that generates encrypted APIKeys with a JSON model that will be used to validate the access to Aura’s public APIs.
  • It is executed with the configuration of the chosen environment. This utility must be executed by the Operations Team and the generated APIKey must only be shared with the team involved in the integration of the corresponding API client.
  • The guidelines are included in the following sections.

Generate an APIKey using the aura-api-key-generator utility

These guidelines correspond to the process that uses the aura-api-key-generator utility as a Docker image.

Prerequisites

• Docker 23.0.5 or higher
• Access to auraregistry.azurecr.io private docker registry.
• The ENCRYPTION_KEY of the environment where the APIKey will be used:

  • kubectl installed in your local host.

  • curl installed in your local host.

  • jq installed in your local host.

  • To obtain the ENCRYPTION_KEY, just execute the following command:

    # substitute {{aura-environment}} with the environment you're configuring
    export AURA_ENVIRONMENT={{aura-environment}}
    
    $ kubectl -n $AURA_ENVIRONMENT get secret aura-bot -o json | jq -r ".data.AURA_ENCRYPTION_KEY|@base64d"
    
    YOUR-ENCRYPTION-KEY
    

Run the tool

Download the Docker image and run the tool by executing the following command:

# Substitute {{aura-encryption-key}} with the ENCRYPTION_KEY obtained in the previous step
$ docker run -e AURA_ENCRYPTION_KEY={{aura-encryption-key}} auraregistry.azurecr.io/aura/aura-api-key-generator:1.0.0 -v 8.3.0 -s aura-services -a kernel -m rw

Usage

> @telefonica/aura-api-key-generator@1.0.0 start
> node lib/index.js --help

process.env.CONFIG_FILE (undefined) not found or not configured, using only process.env

Usage: index -s aura-services:token -e pre -a kernel -v 8.3.0 -m rw

Utility to generate API Key to access the APIs of Aura.  Version: 1.0.0.

Options:
  -V, --version                     Output the version number
  -i, --identifier [identifier]     Unique identifier of the APIKey. Format UUID. If not provided, it will be autogenerated
  -s, --scope [scope]               Comma-separated list of strings containing the API path where this APIKey will be used. Possible values: "aura-services", "aura-services:users,aura-services:token", "aura-services:whatsapp", etc. (By default: "aura-services")
  -e, --enviroment <enviroment>     Environment where the APIKey will be used. Possible values: dev, stg, pre, pro (Choices: "dev", "stg", "pre", "pro". By default: "pro")
  -a, --authorised <client>         Name of the client that will use the APIKey. Usually one of kernel, novum, mh, mp, stb, la, etc. (By default: "kernel")
  -v, --aura-version <auraVersion>  Minimum Aura Platform version to use this APIKey. It should contain the full version of Aura. Example: 8.3.0 (default: "8.3.0")
  -m, --mode <mode>                 Type of access to the API. Possible values: r, w, rw (Choices: "r", "w", "rw". By default: "r")
  -h, --help                        Display help for command

Scope

All public Aura’s APIs are in the aura-services scope, so any APIKey generated with this scope will have access to all Aura’s APIs. But the idea is to use always the minimum scope valid for the specific usage of the client.

For example:

• For those clients that are Aura channels and need to get a Direct Line token from Aura, the scope must be aura-services:token.
• To configure the WhatsApp webhooks of aura-bridge in Kernel, the scope must be aura-services:whatsapp.
• To configure the access from Kernel to aura-services API, the scope must be aura-services:users.
• To configure the access from Kernel to aura-gateway-api in aura-services API, the scope must be aura-ai-services:messaging:write or aura-ai-services:nlp-messaging:write.

Environment

As the specific environment is configured via the ENCRYPTION_KEY, the environment parameter is only used to generate the APIKey with the correct environment name.

The environment name is used to validate the APIKey when it is used to access an API. It only contains the type of the environment: dev, stg, pre or pro.

Authorized

It should contain a human-readable name of the client that will use the APIKey. The usual values are: kernel, novum, mh, mp, stb, la, metaverse.

API Version

It contains the major version of the Aura API that the APIKey will be used.

For example, if the APIKey will be used to access the aura-services API, the API version must be 1. It must be coherent with the version of the API published in Aura’s API documentation.

Mode

It indicates the type of access to the API:

• r: read-only access, it allows to access the API to execute GET operations.
• w: write-only access, it allows to access the API to execute POST, PUT and DELETE operations.
• rw: read-write access, it allows to access the API to execute GET, POST, PUT and DELETE operations.