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-endpointBoth 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-endpointWhen 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:
| Producer | How it names the endpoint |
|---|---|
| CSP | report-to main-endpoint directive |
| COOP, COEP | report-to="main-endpoint" parameter on the header |
| Integrity-Policy | endpoints=(main-endpoint) |
| Permissions-Policy | report-to=main-endpoint parameter per feature, else default |
| Deprecation, intervention, crash | Nothing to add, they go to default (crash reports go to crash-reporting instead when it is declared) |
| Network Error Logging | Cannot 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": ""
}
}
]dispositionis"report"for a Report-Only policy and"enforce"once the policy is enforced.sampleis filled only when the directive carries'report-sample'.- A
report-urifallback posts a different shape: a single object wrapped incsp-report, sent asapplication/csp-report, with kebab-case fields (blocked-uri,effective-directive). A receiver that accepts both must branch on theContent-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:
- The policy is in a
<meta>tag. Report-Only,report-uriandReporting-Endpointsonly work as HTTP headers; a meta policy can usereport-toonly if the response also sendsReporting-Endpoints. - There is no reporting directive. Without
report-to(orreport-uri), CSP violations only appear in the DevTools console. - The endpoint is not HTTPS, or the URL has a typo. Non-secure endpoints are ignored silently.
- The names do not match.
report-to main-endpointmust name an endpoint declared inReporting-Endpointson the same response. - The header is missing on that page.
Reporting-Endpointsonly covers the response that carries it, so a page served by another route or a cached copy may lack it. - Your own collector rejects the CORS preflight. When the endpoint is on
another origin, Chromium sends an
OPTIONSrequest first and needs a2xxanswer withAccess-Control-Allow-Origin(*or the page origin) andAccess-Control-Allow-Headers(*orContent-Type). A hosted collector handles this for you. - 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
- Decide where reports go in choose an endpoint.
- Read what arrives in the report delivery format.
- Browse every report type.
- Understand the two header generations in Report-To vs Reporting-Endpoints.
Sources
- W3C, Reporting API
- W3C, CSP Level 3, report-to directive
- MDN, Reporting-Endpoints header
- MDN, Content-Security-Policy-Report-Only
- MDN, CSP report-to
- MDN, Reporting API
- Chrome, the Reporting API
- Chromium, reporting_uploader.cc (CORS preflight)
- Chromium, SupportedInMeta in content_security_policy.cc
- Chromium, console messages in csp_directive_list.cc