CentralCSP
Reporting APIGet started

Quickstart

Declare a reporting endpoint, point a Content Security Policy at it in Report-Only, read the first report, and fix the setup when nothing arrives.

Last update:

The fastest path to a working setup is three steps: declare an endpoint, point a policy at it in Report-Only, and confirm a report arrives. This page walks through each one with Content Security Policy (CSP) as the first producer, then covers the other policies, the legacy fallback, and what to check when no report shows up.

How it works in one paragraph

A policy or browser feature is the producer: CSP, Cross-Origin-Opener-Policy (COOP), Integrity-Policy, a deprecation warning, a crash. The Reporting API is the transport: the browser queues the reports, batches them, and POSTs them as JSON to the URL you declared, on its own schedule and independently of the page. A report can therefore arrive after the visitor has left the page. Delivery is best-effort: reports can be delayed or dropped, so treat the stream as a strong signal, not as a complete log. The full model is in how the Reporting API works.

1. Declare a reporting endpoint

Add the Reporting-Endpoints response header with a named endpoint.

Reporting-Endpoints: main-endpoint="https://<Endpoint-ID>.report.centralcsp.com"
  • The name (main-endpoint) is arbitrary; a policy references it by that name.
  • The URL must be HTTPS. The browser silently ignores a non-secure endpoint, so an http:// URL or a typo means reports vanish with no error.
  • The endpoint does not have to be on your own origin; pointing it at a hosted collector is the intended pattern.
  • The header applies to the response it is served on. Send it on every page that should report, not only the home page.

You can declare several names in one header and route different policies to different URLs. A special endpoint named default catches report types that have no explicit target: deprecations and interventions, and crashes.

Reporting-Endpoints: default="https://<Endpoint-ID>.report.centralcsp.com",
                     main-endpoint="https://<Endpoint-ID>.report.centralcsp.com"

Full syntax is on the Reporting-Endpoints reference.

2. Point a policy at the endpoint

Reference the named endpoint from a policy. Use CSP in Report-Only so it cannot break the site while you test: the browser reports what the policy would block and blocks nothing.

Reporting-Endpoints: main-endpoint="https://<Endpoint-ID>.report.centralcsp.com"
Content-Security-Policy-Report-Only:
  default-src 'self';
  script-src 'self' 'report-sample';
  style-src 'self';
  img-src 'self';
  object-src 'none';
  base-uri 'none';
  report-to main-endpoint

Both headers must be real HTTP response headers. Content-Security-Policy-Report-Only is not supported in a <meta> element, and neither is Reporting-Endpoints. An enforcing meta policy can carry report-to, but not report-uri.

'report-sample' is optional. With it, a violation caused by an inline script includes the first characters of that script in the report, which helps you find it.

Optional: add the report-uri fallback

The CSP report-to directive is supported in current versions of every major browser. To also get reports from older browsers, add the deprecated report-uri directive with the URL itself. Browsers that support report-to ignore report-uri, so you do not get duplicates.

Content-Security-Policy-Report-Only:
  default-src 'self';
  report-uri https://<Endpoint-ID>.report.centralcsp.com;
  report-to main-endpoint

When to keep or drop it is covered in report-uri, report-to or Reporting-Endpoints.

Other policies use the same endpoint

Each producer attaches to an endpoint with its own syntax:

ProducerHow it names the endpoint
CSPreport-to main-endpoint directive
COOP, COEPreport-to="main-endpoint" parameter on the header
Integrity-Policyendpoints=(main-endpoint)
Permissions-Policyreport-to=main-endpoint parameter per feature, else default
Deprecation, intervention, crashNothing to add, they go to default (crash reports go to crash-reporting instead when it is declared)
Network Error LoggingCannot use Reporting-Endpoints; needs a group in the legacy Report-To header

3. Confirm a report arrives

Trigger a violation, the simplest is to load a script or style the policy does not allow, then watch your endpoint. The browser sends an HTTP POST with Content-Type: application/reports+json and a JSON array. Every entry has the same envelope (type, url, user_agent, age, body); only body changes from one report type to the next.

[
  {
    "type": "csp-violation",
    "age": 53,
    "url": "https://example.com/",
    "user_agent": "Mozilla/5.0 ...",
    "body": {
      "documentURL": "https://example.com/",
      "blockedURL": "https://evil.example/script.js",
      "effectiveDirective": "script-src-elem",
      "originalPolicy": "default-src 'self'; report-to main-endpoint",
      "disposition": "report",
      "statusCode": 200,
      "sample": ""
    }
  }
]
  • disposition is "report" for a Report-Only policy and "enforce" once the policy is enforced.
  • sample is filled only when the directive carries 'report-sample'.
  • A report-uri fallback posts a different shape: a single object wrapped in csp-report, sent as application/csp-report, with kebab-case fields (blocked-uri, effective-directive). A receiver that accepts both must branch on the Content-Type. Both shapes are described in the report delivery format.

Do not expect the report instantly: Chromium batches delivery and can delay it up to about a minute. To verify the setup without building a receiver first, use the Reporting API configuration checker.

4. When no report arrives

Check these, in order:

  1. The policy is in a <meta> tag. Report-Only, report-uri and Reporting-Endpoints only work as HTTP headers; a meta policy can use report-to only if the response also sends Reporting-Endpoints.
  2. There is no reporting directive. Without report-to (or report-uri), CSP violations only appear in the DevTools console.
  3. The endpoint is not HTTPS, or the URL has a typo. Non-secure endpoints are ignored silently.
  4. The names do not match. report-to main-endpoint must name an endpoint declared in Reporting-Endpoints on the same response.
  5. The header is missing on that page. Reporting-Endpoints only covers the response that carries it, so a page served by another route or a cached copy may lack it.
  6. Your own collector rejects the CORS preflight. When the endpoint is on another origin, Chromium sends an OPTIONS request first and needs a 2xx answer with Access-Control-Allow-Origin (* or the page origin) and Access-Control-Allow-Headers (* or Content-Type). A hosted collector handles this for you.
  7. You checked too early. Wait a minute, then reload the page that should violate the policy.

DevTools also shows each violation in the console; for a Report-Only policy, current Chrome ends the message with The policy is report-only, so the violation has been logged but no further action has been taken., which confirms the policy is being evaluated even when no report reaches the endpoint. See debug CSP violations in Chrome DevTools.

5. Move to enforcement

Once reports flow, the next job is to read them, fix what your own pages trigger, allow the third parties you rely on, and only then move the same rules from Content-Security-Policy-Report-Only to Content-Security-Policy. That rollout is described step by step in moving a CSP from Report-Only to enforced.

Next steps

Sources

On this page