/
External Domains Configuration Guide

External Domains Configuration Guide

    Optics is built on Atlassian Forge, and it's Forge itself that blocks scripts, styles, fonts, and API calls to any domain that hasn't been explicitly approved. This is a platform-level security control (Forge's Content Security Policy / egress allowlist), not something Optics implements independently — Optics simply surfaces the configuration screen so admins can manage it without leaving Confluence.

    This protects your Confluence site from loading unapproved third-party content. Site administrators can whitelist trusted domains so that macros (like Easy HTML) can safely pull in external resources such as CDN-hosted scripts, web fonts, or API data.

    Screenshot 2026-08-10 at 12.23.41.png

    Who Can Manage This

    Only Confluence site admins and Confluence admins can add or remove domains from the whitelist. All other users who need an external domain approved should contact their site admin with the request.

    Where to Find It

    Navigate to:
    Confluence settings → Apps → Macros Configuration → External domains

    The External Domains Screen

    The configuration screen includes the following elements:

    Domain URL

    A text field where you enter the full URL of the domain you want to whitelist, including the https:// scheme (e.g. https://cdn.example.com).

    Allowed Usage

    Checkboxes that define what the whitelisted domain is permitted to serve:

    Option

    Purpose

    Option

    Purpose

    Scripts

    Allows loading JavaScript (e.g. from a CDN)

    Styles

    Allows loading CSS stylesheets

    Fonts

    Allows loading web fonts

    Client fetch

    Allows data/API calls made from Easy HTML JavaScript running in the browser

    Backend fetch

    Allows server-side calls to the domain

    Action Buttons

    • Add domain: submits the new domain and usage permissions (enabled once a valid URL is entered).

    • Reload app (apply CSP): reloads Optics so the updated Content Security Policy takes effect.

    Whitelisted Domains

    A list of domains already approved for the site. If none have been configured, this section shows: "No customer-managed domains configured yet."

    How to Add a Domain

    1. Go to Confluence settings → Apps → Macros Configuration → External domains.

    2. In the Domain URL field, enter the domain including https:// (e.g. https://cdn.example.com).

    3. Tick the relevant Allowed usage boxes for what this domain needs to serve:

      • Scripts: if it hosts CDN-delivered JavaScript

      • Styles: if it hosts stylesheets

      • Fonts: if it hosts web fonts

      • Client fetch: if Easy HTML JavaScript needs to call it for data/APIs

    4. Click Add domain.

    5. Confirm the change in the Atlassian approval dialog that appears.

    6. Click Reload app (apply CSP) to apply the updated policy, and refresh the page if the change doesn't take effect immediately.

    Changes are reviewed through an Atlassian approval dialog and can also be managed centrally under Connected apps in Atlassian Administration.

    Using External Scripts in Easy HTML

    If your Easy HTML macro relies on external scripts or API calls, you must also enable JavaScript for that macro: Macros Configuration → Easy HTML → JavaScript (turn on)

    Troubleshooting

    If external content still fails to load after whitelisting a domain:

    • Double-check that you entered the correct host and ticked the correct permission types (Scripts, Styles, Fonts, Client fetch, Backend fetch) for what the macro actually needs.

    • Some external tools, such as webhooksm cannot be called directly from a browser page, even once approved, due to how they're designed to be consumed.

    • If you're unsure why a domain still isn't working, contact support for assistance.