Data hub API credentials

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

Prerequisites

You need the Workspace Admin or Workspace IAM Admin role to create and manage API groups.

Locate workspace credentials

Your workspace has unique identifiers you'll need for all API calls.

1. Click the Workspace settings icon in Data hub.

   

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

3. Note the following values under API Credentials:

   • Workspace ID: A unique identifier for your workspace.
   • Target: Your workspace's API endpoint (base URL).

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

Set up API access

Create and configure API groups

API groups control access permissions and organize your API keys. You can create up to 50 API groups.

To create a new API group:

1. Under API groups, click the group selection dropdown and select + New group.

2. Select an access type:

   • Public: Access to publicly available data only. Use for read-only access to non-sensitive catalog data.
   • Private: Access to both public and restricted data. Use for item collections, event streams, and any integration that reads or writes customer or product data.

3. Name your group.

4. Click Create group.

   

For a Private group, copy your new API Key Secret to authorize API requests.

Generate API group keys

Create a separate private API group for each integration purpose. For example, use one group for event streams and another for item collections. Item collections permissions only appear in a newly created private group and won't be available in groups created for other purposes.

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 per group.

To generate new API keys:

1. Under the Keys section, click + Create new key.

   

2. Copy and store the key values securely. You will only see the private key secret once.

For the Public groups, you'll see the Key ID:

For Private groups, you'll see the Key ID and Key Secret:

You can rotate the API secret at any time—the old secret remains valid for 24 hours after rotation or until you revoke it.

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.

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

2. Select each permission your integration requires:

   • To update records, select Update records.
   • To get job details, select Get job details.

3. Click Save changes to apply the permission configuration.

Permissions map one-to-one with available API operations. Only grant the permissions your integration needs.

API changes and versioning

Bloomreach may update, enhance, or replace APIs over time, including introducing new versions and deprecating older ones. Bloomreach won't materially reduce core functionality during your contract term without providing a reasonably equivalent alternative or transition support, and will give reasonable advance notice of any deprecation that removes an API. Bloomreach may make changes without advance notice to address security vulnerabilities, comply with applicable law, or respond to changes in third-party dependencies.

Next steps

• Use the Item collections API documentation to manage collections programmatically.
• Use the Tracking API to manage event tracking operations.