API Keys Guide

Introduction

API Keys allow users to create applications that integrate with the TrustX app.

The API Keys page allows users to create new keys as well as view and edit existing keys previously created. Accessing the page from the navigation menu will show the following list of all API keys created.

Create a New API Key

To create a new API Key, click the 'Create New API Key' button found under the API Keys menu. This will redirect to a page listing the following properties:

• Name: The name of the API Key. This field is mandatory

• Description: A brief description of the API Key. This field is optional.

• Type: The API Key can be of type Session or Permanent.

  • Session: The key remains active only during the session.
  • Permanent: The key remains active even when a session has not been established.

• Status: The current status of the API Key. Values can be Active, Blocked and Archived.

  • Active: The API Key is available for use.
  • Blocked: The API Key is blocked from use.
  • Archived: The API Key is blocked and archived to be no longer in use.

• Permissions: A list of permissions that the API Key is available to access such as tenants and results.

Permissions

Permissions are defined using the 'Permissions' text field where users can provide a line separated list of permissions for each tenant: TNT#{**tenant**}#{**service**}:{**service**} where:

• TNT#{tenant}# is the tenant that will be granted permissions.
• {service}:{permission} is the service that the tenant will be granted permissions for.

Possible service:permission include:

• ProcessManager:getCloudSecretValues
• ProcessManager:getCloudFunctionByNameAndVersion
• ProcessManager:getProcessInstanceWithParameters
• ProcessManager:getProcessDefinitionFile
• ProcessManager:updateProcessInstance
• ProcessManager:getActivityDefinitionV1BySkyId
• ProcessManager:getCustomDataFormByNameAndVersion
• NotificationService:getWebhookDefinitionByNameAndVersion
• NotificationService:getEmailTemplateByNameAndVersion

Below demonstrates an example granting all permissions to all tenants in TrustX.

TNT#tenant1#*

Users with audit permissions in the Backoffice will not be able to view API Keys that have permissions higher than their role as audit users. When selecting an API Key with higher permissions, users will see that the key is not available and will be unable to issue a token for this key.

Edit an API Key

API Keys can be edited by selecting the edit button from the list of available API Keys. This option is found among the column of Actions available at the right-most column of the API Keys table.

From here, it is possible update properties of the API Key such as the name and description of the API Key.

Issue a Token

A token can be issued for an API Key by clicking the padlock icon found under the Actions column of the API Keys table.

Selecting this icon will auto-generate a new token inside a pop-up modal. From here, a Time To Live (TTL) for this token is also visible. The current default value will be 1,200 seconds.

Example of issued token

Delete an API Key

Once created, an API key can be deleted from the Backoffice. This can be achieved by using clicking the bin icon found under the 'Actions' column of the API key landing page.