Component: API key management

Introduction

Most projects often need to expose the API(s) to allow other services to interact with. We need an approach for secure service-to-service communication. The common approach is using the API Keys. Based on this demand, Casewhere provides the standard component to:

  • Support generating an API key
  • Support managing the API key and its access rights

Feature

To make the API work, we will need to prodide the API key and grant access right(s) to each external service.

In the section Api rights, the developer can manage the list of available access rights. The developer can use it to restrict API key access and set up the specific actions that an API key can carry out.

In the section API keys, the developer can manage the list API keys. Each API key here is used to identify a spectific external service and authorize the request.

Api rights

Api rights list overview

The API rights are the list of available permissions that the developer can grant to a specific API key. An API key can have one or more rights.

In Api right list, you can view all API rights with the information of:

  • API right code: is the code of the API right
  • API right name: is the name of the API right
  • Description: is the description of the API right. It is usually used to describe the information of the API right.
  • Is active: is the status of the API right. If the API right is not active, then this right is disabled and the external system will no longer have this access right

image-20220426101001144

Add a new API right

To add a new API right, first, click on the Add button Then, in Add API right dialog, fill out the fields:

  • Right code: this field is unique, required. You must input code of the API right

  • Right name: this field is required.

  • Description: this field is optional. This field is used to describe the information of the API right.

  • Is active: If this checkbox is ticked, the API will be active.

After filling the information, click on Save and close button to complete adding the API.

image-20220426101048459

Edit a API right

To edit an API right, first, click on the Edit button Then, in Edit API right dialog, fill out the fields:

  • Right code: this field is readonly. We only can edit it once at the creation time

  • Right name: This field is required.

  • Description: This field is optional. This field is used to describe the information of the API right.

  • Is active: If this checkbox is ticked, the API right will be active.

After filling the information, click on Save and close button to complete adding the API.

image-20220426101328499

Delete a API right

To delete a API right, first, select a right. Then, click on the Delete button

If the right is not used for any Api key, a confirmation dialog will be shown. If you select the Yes button, the API right will be deleted immediately. If you select the No button, the deletion will be cancelled.

If the right was already used in a Api key, deletion will be disallowed, and a warning message will be shown.

delele-api-right

Import the API right

To import the API right, first, click on the Import button to open the Import API right dialog

import-api-right

  • Note: All the API right that exists in the destination environment will be overridden. (Detected by transform API right code)

Then, click on the placeholder of the File upload field to open file selection dialog

Next, select a JSON file to import (multiple selection is not supported). After selecting the file, click on the Import button to import the api rights from the JSON file. If you do not want to execute the import process, click on Cancel button.

Export the API right

To export 1 or several API rights in the list, select the rights, then click on the Export button. Then, the JSON file of the selected api rights will be downloaded immediately.

  • Note: All the API rights that exists in the destination environment will be overridden. (Detected by API right code)

To export all the rights in the list, click on Export button. Then, the JSON file of all API rights will be downloaded immediately.

Api keys

Api key list overview

API Keys is a page which manage all of the access keys and their access right(s) for all of the external systems.

In Api key list, you can view all API keys with the information of:

  • API name: is the name of the API key
  • Created at: is the creation date of this API key
  • Modified at: is the last modified date of this API key
  • Is active: is status of the API.
  • Description: is the description of the API key. It is usually used to describe the information of the API key.

image-20220413160151417

Add a API key

To add a new API key, first, click on the Add button Then, in Add API key dialog, fill out the fields:

  • API name: this field is unique and required. You must input name of the API
  • API key: this field is required. We can input or choose to generate a random API key, since the API key itself is an identity by which to identify the external system or the user, it needs to be unique, random and non-guessable. API keys that are generated will also use alphanumeric and special characters. The user can enter a desirable key or choose to Generate the random value.
  • API rights: this field is required. it is used to restrict API Key access and choose specific actions that an API key can carry out.
  • Description: this field is optional. This field is used to describe the information of the API right.
  • Is active: if this checkbox is ticked, the API will be active. Otherwise, it becomes being inactive and the system will reject accessing through this API key

image-20220420110644584

After filling the information, click on Save and close button to complete adding the API.

Edit an API

To edit a API, first, click on Edit button to open Edit API dialog

In the Edit API dialog, you can edit API name, API key, API rights,Description,Is active

image-20220420113835522

After updating the information, click on Save and close button to save the changes. Or you can click on Cancel button to discard the changes.

Delete a API key

To delete a API key, first, click on the Delete button

Then, a confirmation dialog will be displayed. If you select the Yes button, the API key will be deleted immediately. If you select the No button, the deletion will be cancelled.

delete-api-key

Import the API key

To import the API keys, first, click on the Import button to open the Import Data collection Configs dialog

import-api-key

  • Note: All the API keys that exist in the destination environment will be overridden but the generated key will be remained (Detected by API name)

Then, click on the placeholder of the File upload field to open file selection dialog

Next, select a JSON file to import (multiple selection is not supported). After selecting the file, click on the Import button to import the API rights from the JSON file. If you do not want to execute the import process, click on Cancel button.

Export the API key

To export one or several API keys in the list, select the API key(s), then click on the Export button. Then, the JSON file of the selected API keys will be downloaded immediately.

To export all API keys in the list, click on Export button. Then, the JSON file of all API keys will be downloaded immediately.

Extension rules

Casewhere API management component provide the rule below to support the authentication and authorization process:

  • Has Right: Checking if the API key has a specific API right
    • Input: API key, API right
    • Output: true/false

This is a sample. A web trigger invokes a workflow that calls the rule Has Right

webtrigger

Scripted activity inside workflow calls rule Has Right

import-api-key

Installation

Requirements

  • Casewhere 2.6.10 or later

Configuration

  • Import the product
  • Configure the API right and API keys
  • When implementing the web trigger, the developer needs to implement the code to check if the API key is allowed to access to the web trigger or not by querying the information of the API key in the database. Casewhere also provides a common rule mentioned in the section Extension rules to support this checking.

Releases

1.0.0 - 24/02/2022

Changelog

  • API key management

Download (login required): API Key Management v1.0.0