Managing API keys

API keys are codes passed to the Collaboration Server by websites instrumented with the Unblu snippet. API keys act as unique identifiers and have a set of access rights and configuration properties associated with them. They tell the Collaboration Server which set of configuration properties the websites wants to access Unblu with.

Every Unblu account has a default API key. You can create extra API keys to suit your requirements. API keys are commonly used to provide different configurations for Unblu in mobile and desktop web applications, or on different websites that belong to the same organization.

API keys are not security-relevant.

Managing API keys with the Unblu web API

The Unblu web API provides the ApiKeys service with various endpoints to manage API keys.

The service includes endpoints to create, read, update, delete, and search for API keys.

Creating API keys in the UI

Only superadmins, technical admins, and admins may create API keys.

To create a new API key:

Go to the Account Configuration interface.
Click API keys in the navigation menu.
Click New API key in the top-right corner.

A modal window opens.
Add a name and a description for the new API key.

For example, you may use the description to record which web pages, domains, or named areas the key is associated with.
Click Save to create the new API key. The modal page disappears, and the new API key is generated automatically and added to your account.

You can also edit and delete API keys from the Account Configuration interface.

API keys define a configuration scope in Unblu. For more information on configuration scopes, refer to Configuration property scope and the configuration cascade.

Adding API keys to your website

Once you’ve created and configured your API key, you can put it to use on your website. If your website is instrumented with the Unblu snippet, the API key is a query parameter of the URL used to load the snippet:

Listing 1. Unblu snippet example

<!DOCTYPE html>
<html>
<head>
    <script type="text/javascript" defer="defer"
        src="https://unblu.cloud/unblu/visitor.js?x-unblu-apikey=YOUR_API_KEY"></script> (1)
</head>
<body>
    <!-- Your HTML body -->
</body>
</html>

1	Replace `YOUR_API_KEY` with your API key.

The snippet, available in the JavaScript Snippet tab, contains the code you must add to each page of your website that you want to provide access to Unblu on.

Figure 1. API key JavaScript Snippet tab

You can also use the SecureFlow Manager or a tag management system to inject the snippet dynamically.

If your website page is instrumented using the Unblu Visitor JS API, the API key is one of the mandatory parameters needed to configure the API before initializing Unblu.

For more information, refer to Including the Unblu snippet.

Configuring the API key in Visitor Desk URLs

If you want the Visitor Desk to use a particular API key, add the key’s ID to com.unblu.conversation.invitation.visitorDeskApiKeyId in the relevant conversation template. Once configured, the Visitor Desk URL generated in conversations based on the conversation template includes the API as a query parameter. This is the case for all types of Visitor Desk links:

Public links
Invitation links
Webhooks
Web API