Chapter 28. Authenticating with API Keys

API Keys are simple encrypted tokens that are used by third-party applications to consume, in an authenticated manner, the application REST APIs. They allow to query REST APIs with the same authorizations as the user who has created the API Key.

Figure 28.1. Understanding the API Keys Management
Understanding the API Keys Management

An API key can be used to query DOC REST APIs, and needs to be sent through query parameters or headers.

For example, available tasks can be listed using the API Key in query parameters:

GET /api/scenario/application?api-key=36e2326d-a3f5-4a1c-80cd-9c5e61111f5d

Or in the HTTP request headers:

GET /api/scenario/application
X-Api-Key: 36e2326d-a3f5-4a1c-80cd-9c5e61111f5d

API keys are managed from the API Keys management view which can be accessed from the Settings menu in the Topbar. For more details, refer to Section Understanding the API Keys Management View.

Figure 28.2. Accessing the API Keys Management View from the Settings Menu
Accessing the API Keys Management View from the Settings Menu

1. Creating an API Key

[Note]

Note that:

  • In order to create an API Key, you need to be connected to DOC web page with a user who has the API_KEY_BACKOFFICE role in Keycloak.

  • The API key should be stored with care as it cannot be recovered. Lost API Keys need to be deleted and recreated.

Procedure 28.1. To Create an API Key

  1. Connect to the web client as a user with sufficient permissions to proceed. For more details, refer to Section Accessing the Web Client and Part Securing.

  2. In the Topbar Menu Settings, click on Settings > Application Configuration > Permissions. The Permissions management view opens.

  3. In the toolbar, click on . A dialog opens.

  4. Name the API Key (usually with the name of the third-party application that will use it). Optionally give an expiration date to your API Key.

    Figure 28.3. Creating an API Key
    Creating an API Key

  5. Finalize the creation by clicking on CREATE. The API Key is now created and a confirm dialog displays it.

    Figure 28.4. Displaying an API Key
    Displaying an API Key

  6. Click on OK. The API key is listed. In the toolbar, click on to refresh the list if need be.

    Figure 28.5. API Keys Management View
    API Keys Management View

2. Deleting an API Key

To revoke all application access from an API Key, it must be deleted from the API Keys management view.

Procedure 28.2. To Delete an API Key

  1. Connect to the web client as a user with sufficient permissions to proceed. For more details, refer to Section Accessing the Web Client and Part Securing.

  2. In the Topbar Menu Settings, click on Settings > Application Configuration > Permissions. The Permissions management view opens.

  3. In the toolbar, click on . A dialog opens.

  4. Click on DELETE to confirm the deletion.

    Figure 28.6. Deleting an API Key
    Deleting an API Key

    The API Key is now deleted.