API Authorization

The apiAuthorizationHeader option attaches an authorization header to the API requests the Plugin makes to your endpoints. Use it when your feeds, products, templates or file storage endpoints sit behind token-based access control.

Which requests carry the header

The header is added to requests aimed at the endpoints you configure through the api option. Three groups are deliberately excluded:

• Topol's own backend calls, which carry their own plugin key. This covers HTML rendering and preview, test sends, template loading, signed upload URLs, and every AI endpoint.
• Giphy search, used by the GIF block.
• Vimeo oEmbed lookups, used by the video block.

Setting the authorization header

Define the header inside TOPOL_OPTIONS when initializing the Plugin. There are two approaches.

1. Using standard authorization header

This is the most common method (e.g., with Bearer tokens):

apiAuthorizationHeader: "Bearer your_token"

This configuration results in HTTP headers like:

Authorization: Bearer your_token

2. Using custom header names

If your backend expects a non-standard header, or the token has to travel under a custom key, define the header as an object:

apiAuthorizationHeader: {
  "X-Auth-Token": "your_custom_token"
}

This configuration sends:

X-Auth-Token: your_custom_token

The object form accepts more than one entry, and every key becomes its own header:

apiAuthorizationHeader: {
  "X-Auth-Token": "your_custom_token",
  "X-Tenant-Id": "acme"
}

Updating authorization tokens dynamically

When the token needs to be refreshed after expiration or a re-authentication, TopolPlugin.updateApiAuthorizationHeader() replaces it without reinitializing the Plugin:

TopolPlugin.updateApiAuthorizationHeader(new_token);

new_token can be a string or an object that provides header name and the value:

// either string format (standard)
TopolPlugin.updateApiAuthorizationHeader("Bearer new_token_value");
// or object format (custom header)
TopolPlugin.updateApiAuthorizationHeader({
  "X-Auth-Token": "new_token_value"
});

INFO

Keep the shape consistent with what was passed at initialization. A configuration that starts as a string should be refreshed with a string, and one that starts as an object should be refreshed with an object using the same header names.

The configured header is stripped from the options object before it is logged or persisted, so the token does not travel with saved template metadata.