Data hub API prerequisites

Before you can start using Data hub APIs, configure your workspace with proper authentication credentials and permissions. This guide walks you through setting up API groups, generating API keys, and configuring permissions to access Data hub APIs.

Prerequisites

Before setting up API access, you must have one of the required roles (Workspace Admin or Workspace IAM Admin) to create and manage API groups within your organization.

Set up API access

Locate workspace credentials

Your workspace has unique identifiers that you'll need for all API calls. These credentials establish which workspace and environment your API requests target.

1. Click the Workspace settings icon in the Bloomreach Data hub interface.

   

2. Select Access management > API from the left navigation menu.

3. Note the following values:

   • Workspace token: A unique identifier for your workspace.
   • API Base URL: Your workspace's API endpoint.

Keep these values secure and include them in every API request to Data hub.

Create and configure API groups

API groups control access permissions and organize your API keys. Each group can have either Public or Private access type, determining what data the keys can access. You can create ​​up to 50 API groups.

To create a new API group:

1. Under the API groups section, click the dropdown menu and choose + New group.

2. Choose between:

   • Public: Allow access to publicly available data only.
   • Private: Allow access to both public and restricted data.

3. Name your group.

4. Click Create group.

   

In case of Private access type, copy your new secret API key to authorize API requests.

Generate API group keys

API keys authenticate your requests to Data hub. Each key belongs to a specific group and inherits that group's permissions. You can generate ​​up to 20 API keys.

To generate new API keys:

1. Under the Group Keys section, click + Add key.

2. Specify the key name and click Create.

3. For the Public access type, you can see the key name and the API token. For the Private access type, you can see the API key name, key ID, and API secret. You can also rotate the API secret. This creates a new API Secret, and the old one can be used for the next 24 hours or until revoked.

   

Creating multiple keys within a single group allows you to:

• Rotate keys without service interruption.
• Track usage by different systems or environments.
• Revoke access to specific integrations without affecting others.

Configure permissions

API group permissions determine what actions your API keys can perform on Data hub Item collections. Every group has its own permission set that applies to all keys within that group.

To configure permissions:

1. In the Group Permissions section, review the available actions.

2. Check the box next to each permission your integration requires.

   • To update records, check the Update records permission.
   • To get job details, check the Get job details permission.

   The permissions map one-to-one with the available API operations.

3. Follow the principle of least privilege. Only grant permissions necessary for the specific use case.

4. Click Save changes to apply the permission configuration.

Next steps

With your API prerequisites configured, you're ready to:

• Review the Item collections API documentation to manage collections programmatically.