HomeEngagementContentDiscoveryOther resources
API reference

Discovery API Keys

Some public Discovery APIs require an API Key to authenticate the requests. This page will walk you through obtaining and managing your API Keys for Bloomreach Discovery APIs.

Creating a New API Key

The API keys module allows you to create and manage all your API keys in one place.

To create a new API key, follow the steps given below:

  1. Navigate to Setup → Discovery API keys.

  2. Click the Add new API key button on the top right to create a new key.

  3. Give your key a name to identify it later. Try to include details of the purpose for which you will be using the API key. For example, autosuggest-key-prod.

  4. Choose the required access Scopes for the key from your site hierarchy.

  5. Choose the specific Roles for the selected scope, and click the "+ Add roles" button.

  6. After confirming and clicking the Add new API key button on the top right, you will be prompted to copy your key - Please save this value in a secure location at this step, since you will not be able to view this value again.

Scopes and Roles

Scopes

Each API key can be assigned different levels of access (scope):

  • Organization level - The API key will get access to the entire Organization for the assigned roles.
    • Account level - The API key will get access to specific Account(s) within the organization for the assigned roles.
      • Environment level - The API key will get access to specific Environment(s) within the account for the assigned roles.

Follow the link for more details about each level of our user access site hierarchy.

💡

Tip

You can keep separate keys for your Staging and Production environments, by only assigning roles at the environment level.

Roles

For each Scope, the API key can be granted permission to perform certain actions. These permissions are assigned through roles. Discovery API keys currently support the following roles:

  • Personalization studio editor
  • Catalogs & events admin

📘

Inheritance of Roles

Note that the roles applicable to a higher scope level will automatically apply to the lower levels as well. However, you can add different additional roles at the lower levels in the same API key by clicking on "Edit Assignments".

Follow the link for the full list of supported user roles.

Managing API Keys

The Discovery API keys module lists and lets you manage your existing API keys. Navigate to Setup →Discovery API keys in your Bloomreach dashboard and click Manage next to any of the keys from the list.

Here are the allowed modifications on an existing key:

  • Change its name
  • Update the scope levels or roles assigned to it
  • Revoke (Delete) the key