API Authorization

Introduction

Goal

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

Background

APIs exposing development and/or management functionality requires authorization using a token. These tokens are linked with a developer's user identity, and 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 to use 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.

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 currently supported by the following APIs:

📘

Note:

You can also use this page to create your own Authorization Token which will allow you to access our newly available public developer environment. The environment is accessible via publicly shared credentials.
Note that this environment is different from the private environment you acquire access to using your trial developer credentials.

Instructions

  1. Log in to Bloomreach Content using an account with Site Developer privileges.
  2. Navigate to Setup > brXM API token management:
  1. Click on the + API token button in the top right:
  1. Fill in a Token name, choose an Expiration date (up to 1 month in the future), check the Read and/or Write checkboxes, and click on Create. We recommend setting the expiration date as soon as possible, to automatically limit the risk of accidental credential exposure.
  1. 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.
  1. Include the token in the x-auth-token header in your API requests:
x-auth-token: VMpSrbVpCEpNpsPLCntXqFnTBTQmQdnLEYljaRnAkhqbzclevMBrTexENKVmtQYc