Authentication

Introduction

Goal

Obtain and use an authorization token for read and/or write access to management APIs.

Role required

This task requires the Site Developer role.

Background

APIs exposing development and/or management functionality require authorization using a temporary token. These tokens are linked with a developer's user identity, and they can be configured to allow access to all or a subset of functionality available to the developer.

The tokens themselves are intended to be opaque, short-lived, and easy to create and revoke. Bloomreach recommends the use of a separate token for each use case and interaction, with as short a life span as possible, to limit the risk of accidental credential exposure. Using separate tokens for each use case makes it easier to revoke tokens that may have been exposed without disrupting other use cases. Setting a short expiration will revoke tokens and limit risk automatically.

Users with the Site Developer role are limited to creating tokens with 30 days of validity. Users with Site Developer and Site Admin roles are allowed to create tokens of any duration. This limits risk in sensitive environments while allowing trusted developers to create long-lived tokens for use by automated processes.

Tokens are created in the API token management application in Bloomreach Content and passed as x-auth-token header in API requests.

Authorization using the x-auth-token header is supported by all management APIs.

Instructions

1. Log in to Bloomreach Content using an account with Site Developer privileges.
2. Navigate to Setup > brXM API token management:

3. Click on the + API token button in the top right:

4. Fill in a Token name, choose an Expiration date, check the Read and/or Write checkboxes for the APIs you want to use the token with, and click on Create. We recommend setting the expiration date as soon as possible, to automatically limit the risk of accidental credential exposure.

   👍

   Tip

   Scroll down inside the Create API token pop-up to see all the available APIs. For more information about each API see their corresponding reference documentation.

   Please note that UI extensions management and CDP management are both part of the Content Integrations API but can be authorized separately.

5. Copy the token to the clipboard or write it down. This is the only time it will be displayed. We recommend simply creating new tokens at need, rather than attempting to store the token value in a password manager or other long-term storage.

6. Include the token in the x-auth-token header in your API requests:

x-auth-token: <your_token>