Authorization

Introduction

Goal

Configure and access secured Delivery API 2.0 endpoints.

Background

The Delivery API 2.0 endpoints are public by default. Optionally, you can configure each endpoint to be accessible only for authorized access using a JSON Web Token (JWT). Optionally, secured access to unpublished content and projects facilitates preview scenarios.

This page explains how to configure authorized access for an endpoint and how to access a secured endpoint.

Configure authorized access

To configure authorized access to Delivery API 2.0 endpoints, two settings must be specified using the Delivery API Settings Management API:

• A secret, to be used by the client application to obtain a JSON Web Token
• The endpoints to secure: documents, folders, images, assets, openapi, or * for all endpoints.

Make sure to create API token with read and write access to the Delivery API Settings Management API and specify it in every request in the x-auth-token header.

Additionally, the x-resource-version header must be used when updating settings to prevent conflicts.

Retrieve current settings

Send a GET request to the deliveryApiV2 endpoint to retrieve the current settings:

curl --url https://<your-content-host>.bloomreach.io/management/deliveryapisettings/v1/deliveryApiV2 \
--header 'x-auth-token: 57e1de3c-8070-4886-ab6c-20851696227a'

You will receive the settings in JSON format. The default settings are as follows:

{
    "enabled": false,
    "format": "inlined",
    "skipTranslations": false
}

An example of a response showing the Delivery API 2.0 is enabled with two secured endpoints ("folders" and "documents") and a secret "1234567".

{
    "enabled": true,
    "format": "inlined",
    "securedApis": ["folders","documents"],
    "secret" : "1234567",
    "skipTranslations": false
}

Save the x-resource-version response header as you'll need it to update the settings.

Update settings

Send a PATCH request to the deliveryApiV2 endpoint to update the settings and make sure to include:

• The x-auth-token header containing a valid API token
• The x-resource-version containing the latest version number
• The content-type header specifying application/json
• A JSON response body containing the settings to update

For example:

curl --request PATCH \
     --url https://<your-content-host>.bloomreach.io/management/deliveryapisettings/v1/deliveryApiV2 \
     --header 'content-type: application/json' \
     --header 'x-auth-token: 57e1de3c-8070-4886-ab6c-20851696227a' \
     --header 'x-resource-version: c0d6925ead59e5087a2523e666539df9b0b4634c27e8bfbf27d76929d217b367' \
     --data '{ "secret": "1234567" }'

To set or update a secret:

{
    "secret": "1234567"
}

To secure all endpoints:

{
    "securedApis": ["*"]
}

To secure select endpoints ("documents" and "folders" in the example):

{
    "securedApis": [
        "documents",
        "folders"
    ],
}

You can set a secret and specify secured endpoints in a single request:

{
    "secret": "1234567",
    "securedApis": [
        "documents",
        "folders"
    ],
}

Access a secured endpoint using a JSON Web Token (JWT)

Obtain a token

The client must know the secret to obtain a JWT token to communicate with the secured endpoints. The secret is shared between the client (for example, an SSR SPA) and the Bloomreach Content application.

❗️

Important

The secret should never be shared with third-party clients, such as a user's browser: the browser should only get the JWT to interact with the endpoints.

To obtain a JWT token that can be used in an authorization header, send the following request to the auth endpoint (assuming the stored secret is "1234567"):

curl -url https://<your-content-host>.bloomreach.io/delivery/site/v2/auth \
--header 'Content-Type: text/plain' \
--data '{ \
    "secret":"1234567" \
}'

The response will be similar to the following:

{  
  "access_token" : <token>,  
  "token_type" : "Bearer",  
  "expires_in" : 3600  
}

The created token will be valid for all endpoints.

If you need a token that is only authorized for a specific set of scopes, for example, only "documents" and "images"
, you can obtain a JWT with a request like the following:

curl --url https://<your-content-host>.bloomreach.io/delivery/site/v2/auth \
--header 'Content-Type: application/json' \
--data '{
    "secret":"1234567",
    "scopes":["images", "documents"]
}'

If you want to include unpublished content in the response, specify preview as true in the request:

curl --url https://<your-content-host>.bloomreach.io/delivery/site/v2/auth \
--header 'Content-Type: application/json' \
--data '{
    "secret":"1234567",
    "preview":"true"
}'

If you want to include unpublished content from a project, specify the project identifier in addition to preview:

curl --url https://<your-content-host>.bloomreach.io/delivery/site/v2/auth \
--header 'Content-Type: application/json' \
--data '{
    "secret":"1234567",
    "preview":"true",
    "project":"v5BHR"
}'

Use a token to access a secured endpoint

To access a secured endpoint, the Authorization request header must contain a valid JWT token. The token must include the requested endpoint in its scope (or have "scopes":["*"]). For example, a request to a secured "folders" endpoint should look like the following:

curl --url https://<your-content-host>.bloomreach.io/delivery/site/v2/folders \
     --header "Authorization: Bearer <token>" 

If the token is valid and allows scope "folders," the "folders" endpoint will process the request and return the expected response.

If the token is invalid (for example, verification fails because it has been tampered with), the response will be a 401 "Unauthorized":

{"error":"Unauthorized","message":"Invalid token","status":401}

If the token has expired, the returned message will be:

{"error":"Unauthorized","message":"JWT token has expired","status":401}

When sending a request without an Authorization header to a secured endpoint, a 401 "Unauthorized" response will be returned:

{  
  message: "Unauthorized"  
}

Token expiration

By default, the token will be valid for 1 hour. Bloomreach can configure a different default expiration time for your environment on request.

Stateless

The JWT-based access is stateless and does NOT require cluster node affinity.