Strict Content Security Policy (CSP) Requirements for Termly Consent Banner

Purpose

This guide explains exactly what CSP rules you need to add so the Termly consent banner and preference center work correctly on websites with strict security policies. Consider Content Security Policy (CSP) as a whitelist for your website: only authorized domains are permitted to load scripts, styles, images, or frames. If Termly is not included on this list, the banner will either fail to display or may malfunction.

Use this SOP when:

• A customer runs a locked‑down CSP and sees Termly flagged in their CSP report or browser console.
• They ask which domains must be whitelisted for Termly.
• They want to know whether Termly’s Consent Management Platform (CMP) is compatible with a strict CSP.
• The error is the same as below.

How to know if this is a Strict CSP issue?

A clear sign that a site is encountering a strict Content Security Policy (CSP) issue is when browser errors explicitly mention blocked connections or ignored directives. For example, if you see messages like:

• “Refused to connect to 'https://eu.consent.api.termly.io' because it violates the following Content Security Policy directive: connect-src…”
• “The directive 'frame-ancestors' is ignored when delivered via an element.”

These errors indicate that your CSP rules are too restrictive. In practice, this means your site is preventing Termly’s cookie banner from saving consent because the required API endpoints aren’t whitelisted. When CSP blocks the banner’s network calls, user choices can’t be stored, so the banner reappears on every page load.

Quick Response to clients:

"Yes, Termly is compatible with strict CSP. You just need to whitelist a few Termly domains and allow inline styles for the banner and GPC toast.

You can add this script:

script-src 'self' https://app.termly.io;
connect-src 'self' https://app.termly.io https://us.consent.api.termly.io https://eu.consent.api.termly.io;
style-src 'self' https://app.termly.io 'unsafe-inline';
img-src 'self' https://app.termly.io data:;
frame-src 'self' https://app.termly.io;

Or

"The issue occurs because your current Content Security Policy is blocking Termly’s consent API calls, which prevents the banner from saving user choices. To resolve this, please add/edit your CSP header and this script:

Content-Security-Policy: 
  script-src 'self' https://app.termly.io;
  connect-src 'self' https://app.termly.io https://us.consent.api.termly.io https://eu.consent.api.termly.io;
  style-src 'self' https://app.termly.io 'unsafe-inline';
  img-src 'self' https://app.termly.io data:;
  frame-src 'self' https://app.termly.io;
  frame-ancestors 'self';

Please add this separately in your CSP Header (if this does not appear):

X-Frame-Options: SAMEORIGIN

CSP Requirements by Directive

1. script-src 

Required: https://app.termly.io 

Reason: This is where the main Termly script (embed.min.js) lives. Without it, the banner cannot load. 

Analogy: Imagine the banner is a play. script-src is the stage manager; if you don't let them in, the show never starts. 

2. connect-src 

Required:

- https://app.termly.io

- https://us.consent.api.termly.io 

- https://eu.consent.api.termly.io 

Reason: These endpoints fetch your banner configuration, consent data, and log statistics. 

Analogy: These are the backstage walkie-talkies. The banner needs to phone home to get its script and report back. 

3. style-src 

Required: https://app.termly.io + 'unsafe-inline' 

Reason: Inline styles are used for banner layout and the GPC toast. 

Analogy: Styles are the costumes. Some are sewn directly onto the actors (inline). If you forbid that, the costumes fall off. 

4. img-src 

Required: https://app.termly.io + data: 

Reason: Logos and static images come from Termly. The policy viewer uses base64-encoded background images.

Analogy: These are the posters and props. Some are printed (Termly images), some are stickers (base64 data). 

5. frame-src 

Required: https://app.termly.io 

Reason: The policy viewer and embedded policies load inside an iframe from Termly. 

Analogy: This is like a guest speaker joining your play via video call. You need to allow their screen to appear. 

6. Optional Simplification 

If you are comfortable with broader rules: default-src 'self' https://app.termly.io; 

This covers most cases, but strict CSP clients usually prefer explicit per-directive rules.

Note: If you block 'unsafe-inline', the banner may look broken, or the GPC toast will not appear. We do not require unsafe-eval.

Example Strict CSP Snippet

Note: This is a template only. Merge with your existing CSP and other third-party requirements.

Content-Security-Policy: 
default-src 'self';
script-src 'self' https://app.termly.io;
connect-src 'self' https://app.termly.io https://us.consent.api.termly.io https://eu.consent.api.termly.io;
style-src 'self' https://app.termly.io 'unsafe-inline';
img-src 'self' https://app.termly.io data:;
frame-src 'self' https://app.termly.io;
font-src 'self';
object-src 'none';
base-uri 'self';
form-action 'self';

Support Workflow 

Step 1: Collect Information

When a customer reports CSP issues, or you think this is a CSP issue, begin by gathering the following details:

• Customer site URL(s): Identify the specific pages where CSP is active.
• Current CSP header: Request the full CSP configuration if available.
• Violation evidence: Obtain browser console logs and/or CSP violation reports (screenshots or text).

This information establishes the baseline for troubleshooting and helps confirm whether Termly resources are being blocked.

Step 2: Respond to the Customer

Provide the customer with clear guidance and actionable steps:

1. Share resources:
   • Provide the Quick Response.
   • Share the Example Strict CSP Snippet for reference.
2. Highlight key requirements:
   • Required Termly domains: app.termly.io, *.consent.api.termly.io
   • The necessity of style-src 'unsafe-inline' banner styling and GPC toast.
   • Clarify that it unsafe-eval is not required.
3. Ask them to:
   • Ensure the CSP update has been applied to the page where the Termly script runs.
   • Suggest temporarily relaxing CSP for Termly domains to verify banner functionality before re‑tightening rules.

Step 3: Escalate if Needed

Escalate to engineering when:

• The customer’s CSP matches the documented requirements, but the banner or policy viewer still fails.
• CSP violation reports show Termly resources being blocked despite recommended directives.

When escalating: 

FAQ 

Q: Do I need 'unsafe-eval'? 

A: No. Termly does not require 'unsafe-eval'. 

Q: Can I avoid 'unsafe-inline'? 

A: Not yet. Inline styles are required for the banner layout and GPC toast. 

Q: What happens if I block Termly domains? 

A: The banner will not load, or the policy viewer will fail. 

Q: Can I just allow default-src 'self' https://app.termly.io? 

A: Yes, but explicit per-directive rules are safer for strict CSP setups.