Authentication

To authenticate an API request, you must generate an API key and use it as value for the request header x-api-key.

Create an API key

In the side panel, click on the drop-up menu with your name.

Figure 1: Drop-down menu with your name.

Click on the Settings option on the drop-up menu.
On the Settings page, navigate to the API Keys tab.
Click on the + CREATE API KEY button.
Enter a descriptive name for the key and click on the GENERATE API KEY button.

Fig. 1: Create new API key — Figure 2: Create a new API key.

Click on the Copy button. Save the API key somewhere safe. The API key cannot be viewed or copied after this step.

Fig. 2: Copy the newly created API key. — Figure 3: Copy the newly created API key.

Performing API tests using the API key

Test the API in Zenskar documentation

Head over to the API documentation you would like to test.
Add the API key to the header, as shown below. This action will create an x-api-key header:

Fig. 3: Preparing for an API test — Figure 4: Prepare for an API test.

Some APIs will require you to fiill in the mandatory organisation header.

Fig. 4: The mandatory query parameter: organization — Fig. 4: The mandatory header: organisation.

The value for the organisation header can be obtained by navigating to the General tab on the Settings page. The organisation header accepts a valid universally unique identifier (UUID).

Fig. 5: Get the value for `organisation` header. — Figure 5: Get the value for `organisation` header.

🚧
Note
If the mandatory organisation header is left empty or if a wrong UUID is entered, you may receive an HTTP 403 error with the following message in the response:
{  
   "Message": "User is not authorized to access this resource with an explicit deny"  
}

Fig. 6: HTTP 403 error response — Figure 6: HTTP 403 error response.

Fill in the other necessary optional query parameters.
Click on Try It!. A successful test will result in an HTTP 200 status with a proper JSON response as shown below.

Fig.7: HTTP 200 success response — Figure 7: HTTP 200 success response.

Test the API using tools like Postman

The API keys can be used to test the APIs using tools such as Postman or Thunder Client. You should refer to tool-specific instructions.

Deleting an API key

Click on the drop-up menu with your name in the side panel.
Navigate to Settings > API Keys.
Click on the button with the trashcan icon.