Skip to content
Documentation
Custom HTML, CSS & JavaScript
Security and limitations

Security and limitations

Custom macro source is powerful: it can run browser JavaScript. The app therefore renders it inside an additional sandboxed iframe that is separated from Confluence, the Forge bridge, and the trusted macro renderer.

What is allowed

The sandbox is intended for self-contained, browser-native content:

  • inline HTML, CSS, and JavaScript;
  • DOM interaction and event handlers inside the macro;
  • data- and blob-backed images, fonts, media, and downloads;
  • forms and JavaScript form handlers that remain within the rendered document.

What is blocked

The runtime Content Security Policy and iframe sandbox deliberately block or omit support for:

  • external scripts, stylesheets, images, fonts, media, and nested frames;
  • fetch, XMLHttpRequest, WebSocket, and other connections to external services;
  • external form submission;
  • access to the Confluence page, Forge bridge, or macro configuration from user code;
  • the legacy Connect AP.* API;
  • native simple dialogs: alert(), confirm(), prompt(), print(), and beforeunload dialogs;
  • popups, top-level navigation permissions, pointer lock, and presentation permissions.

These restrictions are why a macro that needs data from another system should be redesigned rather than attempting to embed its API key or fetch code here.

Important boundary: same-frame navigation

The sandbox prevents normal network APIs, but it is not an absolute no-egress boundary against a malicious macro author. A link or script can still navigate its own sandboxed frame to an external URL. That navigation can initiate a request before the parent renderer restores the original macro display.

Do not place sensitive information in a URL, and do not treat the macro as a secure execution environment for untrusted authors. Page-edit permissions remain the authority that controls who can create or modify macro source.

Practical safety guidance

  • Only use source you understand and trust.
  • Review pasted JavaScript before publishing it.
  • Never embed credentials, personal data, access tokens, or private URLs in a macro.
  • Keep content self-contained; do not rely on external assets or APIs.
  • Prefer an approved integration or a purpose-built Confluence app when the content needs privileged data or access to another system.

Troubleshooting restrictions

If content fails silently, inspect the browser developer console while viewing the page. Typical causes are an external dependency, a blocked network call, a legacy AP.* call, or an unsupported native dialog. The app intentionally does not provide a network fallback or expose source diagnostics in the page.