Delivery API JWT Authentication

Info: Available in brXM 14.2.1 and later.

Overview

This page describes how to use JSON Web Token (JWT) authentication to access preview data for a channel through the Delivery API.

When to Use JWT Authentication

By default, the Delivery API (formerly known as the Page Model API) returns only published pages and content when accessed via a live endpoint. To retrieve unpublished pages and content—such as when rendering a channel preview in Experience manager—an external frontend application must authenticate using a JSON Web Token (JWT).

The Bloomreach SPA SDK includes built-in support for JWT-based preview channel authentication. Channel preview works without additional configuration for any single-page application (SPA) built with the SDK.

If you do not use the SPA SDK—for example, when working with an unsupported frontend framework—you must implement JWT authentication in your frontend application.

Implementation

Configure the Preview Channel URL

Set the external frontend application's URL in the org.hippoecm.hst.configuration.channel.PreviewURLChannelInfo_url property on the relevant channel node. For example:

/hst:myproject/hst:configurations/myproject/hst:workspace/hst:channel/hst:channelinfo:
  jcr:primaryType: hst:channelinfo
  org.hippoecm.hst.configuration.channel.PreviewURLChannelInfo_url: http://localhost:3000

How JWT Authentication Works

When Experience manager requests the preview channel for the first time, it appends a token query parameter containing a JWT to the external frontend application's URL. For example:

http://localhost:3000/?token=xxxxx.yyyyy.zzzzz

To access preview channel data through the Delivery API, the frontend application must include this token in the Authorization header using the Bearer schema. Example:

Authorization: Bearer xxxxx.yyyyy.zzzzz

Configure a Custom Header

The header used to transmit the JWT is set in the HST container configuration properties file. The default configuration is:

jwt.token.authorization.header = Authorization

If your project already uses the Authorization header for another purpose (such as Spring Security), you can specify a different header name. For example:

jwt.token.authorization.header = HST-Authorization

When using the SPA SDK, you can configure the header name by setting the authorizationHeader option in the initialize function. The default value is "Authorization". See the SPA SDK configuration documentation for details.