Developers

API Reference

GPCGuard exposes an API-layer GPC decision endpoint for configured customer sites. Customers still wire HONORED outcomes into their CMP, tag manager, CDP, server-side events, and ad partners.

Sec-GPC Request

curl -X POST \
  "https://<project-ref>.supabase.co/functions/v1/gpc-signal?domain=<your-domain>" \
  -H "Origin: https://<your-domain>" \
  -H "Sec-GPC: 1" \
  -H "Content-Type: application/json"

navigator.globalPrivacyControl

if (navigator.globalPrivacyControl === true) {
  await fetch("https://<project-ref>.supabase.co/functions/v1/gpc-signal?domain=<your-domain>", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
  })
}

Success Response Shape

{
  "gpc_enabled": true,
  "decision_reason": "gpc_opt_out_honored",
  "decision_state": "ACKNOWLEDGED",
  "policy": {
    "honored": true,
    "sale_opt_out": true,
    "sharing_opt_out": true,
    "targeted_advertising_opt_out": true
  },
  "confirmation": "[site confirmation text]",
  "compliance_standard": "2026-GPC-SPEC",
  "response_code": 200,
  "signal_source": "header",
  "provenance_class": "UNVERIFIED_BROWSER",
  "signal_id": "sig_[redacted]"
}

See the full field reference in Decision Schema.

Outcome Definitions

HONORED / ACKNOWLEDGED: A valid GPC request was processed and policy flags were returned for customer handoff.
DENIED: A compliance-critical guard rejected the request or the policy did not honor the signal.
FAILED: The request hit an internal failure path; review logs and retry after configuration or service recovery.

Common Errors

400: Missing or invalid domain parameter / oversized body
401: Invalid or revoked API key
403: Inactive site, domain not verified, or DPA not accepted (code: site_inactive | domain_unverified | dpa_not_accepted | dpa_version_stale)
404: Site not found
429: Rate limit exceeded
503: Circuit open / rate limiting unavailable (API-key lane)

Guard Chain

Rate limit

Rejects abusive or excessive request patterns before policy work (authoritative distributed limits + local burst cushion).

Site exists

Confirms the domain maps to a configured customer site.

Provenance

A valid API key (X-API-Key, site-bound) produces SERVER_AUTHENTICATED evidence; requests without a key are UNVERIFIED_BROWSER observations. Origin/Referer headers never authenticate.

CORS (policy only)

Origin is compared canonically (scheme + hostname + port) and only decides whether the browser may read the response — it never authorizes processing.

Site active

Stops processing for inactive sites.

Domain verified

Production processing requires proof of domain control (DNS TXT verification).

DPA accepted

Requires the current server-canonical DPA version to be accepted.

Circuit breaker

Pauses processing when the site safety circuit is open.