Platform Documentation

Build and operate ConsentKit with one public reference.

Install the widget, understand the consent model, connect Google Consent Mode, review API contracts, and troubleshoot production integrations without digging through source repositories.

Platform

What ConsentKit does

ConsentKit is an America-first consent management platform. It detects visitor jurisdiction, renders a state-appropriate privacy interface, blocks or unlocks tracking categories, records consent choices, and keeps Google Consent Mode in sync.

Edge widget

A small JavaScript widget is served from Cloudflare and receives server-side location hints before rendering.

Consent API

The API records consent actions, returns site configuration, manages authentication, and handles billing webhooks.

Customer dashboard

Site owners create sites, copy install tags, review consent logs, export CSVs, and manage plan status.

Audit database

Consent records are stored with hashed IP metadata, user agent context, action type, jurisdiction, and timestamp.

Public architecture

Website

Visitor loads page

Widget edge

Location hint injected

Consent UI

Banner or link appears

API ledger

Choice is recorded

Install

Quick start

1

Create a site

Sign up or sign in to the dashboard, add your domain, and copy the generated Site ID.

2

Install the script

Paste the widget tag into your site head, GTM container, ecommerce theme, or app layout.

3

Verify detection

Load the page, check for the right regional experience, and confirm consent events in the dashboard.

4

Tune settings

Add extra domains, set colors, decide whether to force a banner or link, and connect billing when needed.

New to ConsentKit? Create a free account and the dashboard generates this same install tag with your Site ID filled in.

HTML install
<script
  src="https://widget.consentkit.us/v1.js"
  data-site-id="YOUR_SITE_ID"
  async
></script>

Account

Sign in with Google

The dashboard login and signup pages offer one-click Google sign-in next to the classic email and password form. When the Google account email matches an existing ConsentKit account, you land in the same account, so both sign-in methods stay interchangeable.

One-click access

Available on both the login and signup pages. Skips the password form and issues a standard 7-day session.

Same account either way

Matching emails resolve to one account. Sites, consent logs, and billing state are identical no matter how you sign in.

Works with team invites

Invitees can accept a team invite with whichever sign-in method they already use, Google or password.

Widget

Widget behavior and integration

How the widget decides what to show

  • EU, EEA, UK, and similar visitors see an explicit opt-in banner.
  • Covered US state visitors see an opt-out link or privacy choices interface.
  • GPC-required states automatically receive an opt-out action when the browser broadcasts Global Privacy Control.
  • Permissive regions can avoid unnecessary popups while still recording configured consent behavior.

Public JavaScript API

ConsentKit.getPreferences()
ConsentKit.showPreferences()
ConsentKit.getBlockedCookies()
ConsentKit.getDetectedTracking()
AttributeStatusPurpose
data-site-idRequiredYour ConsentKit Site ID.
data-apiOptionalDefaults to https://api.consentkit.us.
data-modeOptionalDefaults to auto. Can force banner or link behavior when enabled in configuration.
data-debugOptionalEnables verbose console logging for installation checks.
data-auto-initOptionalSet to false if you need to call ConsentKit._init() manually.
Next.js install
import Script from "next/script";

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script
          src="https://widget.consentkit.us/v1.js"
          data-site-id="YOUR_SITE_ID"
          strategy="afterInteractive"
        />
      </body>
    </html>
  );
}
GTM denied defaults
gtag("consent", "default", {
  ad_storage: "denied",
  ad_user_data: "denied",
  ad_personalization: "denied",
  analytics_storage: "denied",
  functionality_storage: "granted",
  security_storage: "granted",
  wait_for_update: 500
});

Widget

Widget placement and theming

Every plan, including Free, controls where the privacy element sits and how the widget presents itself. Placement, theme, and the always-on banner option never require an upgrade.

SettingChoicesDefaultBehavior
PositionBottom right, bottom left, or banner barBottom rightPlaces the Your Privacy Choices element shown in opt-out jurisdictions.
ThemeAuto, light, or darkAutoAuto samples the host page background and matches it; the visitor OS preference breaks ties.
Show consent banner to all visitorsOn or offOffOn upgrades US opt-out visitors from the privacy link to the full banner; categories stay allowed until an explicit reject.

Auto theme detection

The widget reads the host page background and renders dark or light to match it. When the page yields no usable color, the visitor’s OS preference breaks the tie. A manual light or dark override is always available.

Opt-out semantics stay intact

The always-on banner changes presentation, not consent logic: visitors in US opt-out states keep categories allowed until they explicitly reject, exactly as those laws expect.

Paid plans

Appearance customization

Starter and above unlock the full banner design controls from the site configuration page in the dashboard.

ControlWhat it changes
Button colorFill color for the accept, reject, and save action buttons.
Button textCustom labels for the Accept, Reject, and Save actions.
Banner backgroundBanner fill color. Text and button contrast adapt automatically.
Text colorBanner copy and preference dialog text.
FontsSystem UI, Inter, Editorial Serif, or Mono.
Custom CSSA custom stylesheet injected alongside the widget for full design control.

Free plan behavior

On the free plan these controls are locked: saving a non-default value returns an upgrade prompt. Clearing a field back to its default always works, so nothing gets stuck after a downgrade.

Free and Starter

The Powered by ConsentKit badge rides along on the widget at these tiers.

Pro

Remove ConsentKit branding: the badge can be turned off from the site configuration page.

Agency

White-label branding: present the widget fully as your own for client sites.

Install

Google Tag Manager template

Teams that deploy tags through Google Tag Manager can install ConsentKit with the official GTM template instead of editing site code. The template loads the widget and applies the Google Consent Mode v2 denied defaults shown in the Widget section, so analytics and advertising tags stay quiet until the visitor decides.

1

Download the template

Get template.tpl from the gtm-template folder of the public ConsentKit repository.

2

Import into GTM

In Google Tag Manager, open Templates, create a new tag template, and import template.tpl.

3

Configure the tag

Add a tag from the ConsentKit template, paste your Site ID, and keep the bundled Consent Mode defaults.

4

Fire early, then publish

Use the Consent Initialization - All Pages trigger so defaults land before any Google tag, and submit the container.

The GTM Community Template Gallery listing is not live yet. Until it is, manual import from the public repository is the supported path.

Jurisdictions

Compliance model

ConsentKit maps visitor location to the matching consent experience. The platform helps with technical consent collection and signal handling, but it does not replace legal advice.

RegionLawEffectiveModelWidget UIGPC
CaliforniaCCPA/CPRAJan 1, 2020Opt-out linkDo Not Sell or Share My Personal InformationRequired
VirginiaVCDPAJan 1, 2023Opt-out linkYour Privacy ChoicesOptional
ColoradoCPAJul 1, 2023Opt-out linkYour Privacy ChoicesRequired
UtahUCPADec 31, 2023Opt-out linkYour Privacy ChoicesOptional
ConnecticutCTDPAJul 1, 2023Opt-out linkYour Privacy ChoicesRequired
MontanaMCDPAOct 1, 2024Opt-out linkYour Privacy ChoicesRequired
OregonOCPAJul 1, 2024Opt-out linkYour Privacy ChoicesRequired
DelawareDPDPAJan 1, 2025Opt-out linkYour Privacy ChoicesRequired
IowaICDPAJan 1, 2025Opt-out linkYour Privacy ChoicesOptional
IndianaICDPAJan 1, 2026Opt-out linkYour Privacy ChoicesOptional
TennesseeTIPAJul 1, 2025Opt-out linkYour Privacy ChoicesOptional
TexasTDPSAJul 1, 2024Opt-out linkYour Privacy ChoicesRequired
FloridaFDBRJul 1, 2024Opt-out plus sensitive-data handlingYour Privacy ChoicesOptional
NebraskaNDPAJan 1, 2025Opt-out linkYour Privacy ChoicesRequired
New HampshireNHPAJan 1, 2025Opt-out linkYour Privacy ChoicesRequired
New JerseyNJDPAJan 15, 2025Opt-out linkYour Privacy ChoicesRequired
MinnesotaMNCDPAJul 31, 2025Opt-out linkYour Privacy ChoicesRequired
MarylandMODPAOct 1, 2025Opt-out linkYour Privacy ChoicesRequired
KentuckyKCDPAJan 1, 2026Opt-out linkYour Privacy ChoicesOptional
Rhode IslandRIDTPPAJan 15, 2026Opt-out linkYour Privacy ChoicesOptional
EU/EEA/UKGDPR/UK GDPRMay 25, 2018Opt-in bannerAccept, reject, and manage preferencesNot applicable

GPC handling

When a supported browser sends Global Privacy Control in a state that requires or expects it, ConsentKit stores an opt-out style consent action and denies analytics and marketing categories.

Google Consent Mode v2

ConsentKit sets denied defaults early and updates analytics_storage, ad_storage, ad_user_data, and ad_personalization after a visitor choice.

Server verification

The API can store server-derived jurisdiction fields alongside the client-reported law, making later audits easier to review.

Compliance

IAB TCF v2.3 (EU/UK/CH)

For GDPR-mode traffic (EEA, UK, and Switzerland), ConsentKit implements the IAB Transparency and Consent Framework v2.3, so ad tech vendors on your pages can read consent signals the standard way.

  • Exposes the standard __tcfapi interface and generates the Transparency & Consent string, including the mandatory disclosed-vendors segment.
  • The Global Vendor List loads through the ConsentKit edge proxy, so visitors never call third-party infrastructure to resolve it.
  • TCF activates only in GDPR mode. US opt-out visitors are unaffected and never get a TCF signal.

Configure it per site in the dashboard under Configuration, on the TCF / IAB Europe card: enable the toggle and paste your vendor IDs from the IAB Global Vendor List.

Registration status

ConsentKit is pursuing IAB Europe registration and Google CMP certification; the CMP ID ships as placeholder 0 until registration completes. The integration itself is fully functional today.

Dashboard

Dashboard operations

Create and manage sites
Copy install code
Register production domains
Review consent log history
Export records to CSV
Inspect regional activity trends
Configure widget colors and behavior
Start checkout or open the billing portal
Invite team members on paid plans

Direct route note

Dashboard deep links are designed for in-app navigation. If a direct browser refresh on a site-specific page fails, return to the dashboard home and open the site from the list.

Collaboration

Team accounts

Paid plans can invite team members to share the workload. Invites are plain links, so onboarding a teammate takes seconds and never depends on email delivery.

1

Create an invite link

The owner opens Dashboard → Account and generates an invite link. Links stay valid for 7 days.

2

Share it anywhere

Send the link over chat, email, or a ticket. ConsentKit never needs the invitee's email in advance.

3

Invitee signs in

The invitee opens the link while logged in to their own ConsentKit account and reviews the invite.

4

Accept and collaborate

Once accepted, the owner's sites appear in the member's dashboard with full site-level control.

What members can do

Members manage sites, domains, widget settings, and consent data across the owner’s account, as if it were their own.

What stays owner-only

Billing and team administration never delegate. Members cannot change plans, open the billing portal, invite others, or remove anyone.

Clean exits

Leaving a team restores the member’s own account and sites exactly as they were. Owners can revoke invites or remove members at any time.

Developers

API reference

API base URL is https://api.consentkit.us. Dashboard endpoints use JWT authentication. Widget configuration and consent recording are public routes with domain and rate-limit protections. Site read endpoints also accept per-site API keys (Pro and above) as Bearer tokens.

API examples
curl https://api.consentkit.us/api/v1/sites/YOUR_SITE_ID/config

curl -X POST https://api.consentkit.us/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"your-password"}'
MethodEndpointPurpose
GET/healthPublic health check for the API service.
POST/api/v1/auth/registerCreate a dashboard user and receive a JWT.
POST/api/v1/auth/loginAuthenticate and receive a 7-day JWT.
POST/api/v1/auth/googleAuthenticate with a Google ID token; lands in the same account when the email matches.
POST/api/v1/auth/forgot-passwordEmail a password reset link. Always responds generically.
POST/api/v1/auth/reset-passwordSet a new password from a reset token.
POST/api/v1/auth/verify-emailConfirm an email address from a verification token.
GET/api/v1/meReturn the current authenticated user.
GET/api/v1/sitesList sites owned by the authenticated user.
POST/api/v1/sitesCreate a new site with a name and domain.
GET/api/v1/sites/:siteId/configPublic widget configuration endpoint.
PUT/api/v1/sites/:siteId/configUpdate owned site name, domains, features, and customization.
POST/api/v1/consent/recordPublic endpoint used by the widget to record consent choices.
POST/api/v1/public/scanPublic cookie scan backing the free scanner tool.
GET/api/v1/sites/:siteId/consentsList consent records for an owned site.
GET/api/v1/sites/:siteId/statsReturn consent volume and category statistics.
GET/api/v1/sites/:siteId/logsList raw consent log entries for a site.
GET/api/v1/sites/:siteId/analyticsReturn aggregate analytics series for a site.
POST/api/v1/sites/:siteId/pageviewPublic beacon used by the widget to meter monthly pageviews.
GET/api/v1/teamList team members and pending invites. Owner only.
POST/api/v1/team/invitesCreate a 7-day team invite link. Owner only, paid plans.
POST/api/v1/team/invites/:token/acceptAccept a team invite while signed in to any account.
POST/api/v1/team/leaveLeave a team and restore your own account.
POST/api/v1/keysCreate a per-site API key. Pro and above; the full key is shown once.
GET/api/v1/keysList API keys for a site (prefixes only).
DELETE/api/v1/keys/:idRevoke an API key.
POST/api/v1/billing/checkoutCreate a Stripe Checkout Session for a paid plan.
POST/api/v1/billing/portalCreate a Stripe Customer Portal session.

Developers

API keys (Pro)

Pro and Agency sites can mint per-site API keys from the site configuration page for read-only programmatic access. Send the key as a Bearer token: Authorization: Bearer ck_live_...

  • Keys read consents, stats, analytics, and raw logs for their own site only — writes stay on the dashboard JWT.
  • Each key is rate limited to 60 requests per minute, independent of other keys and dashboard sessions.
  • The full key is shown once at creation; afterwards the dashboard lists prefixes only, and keys can be revoked at any time.

Plans

Billing and plan capabilities

Paid upgrades use Stripe Checkout and the Stripe Customer Portal. Managed Payments is enabled for production checkout, and plan state is reflected in the dashboard after webhook processing. Every paid plan can be billed monthly or annually — annual billing includes 2 months free, and the billing interval is chosen at checkout or from the dashboard billing page.

PlanPriceSitesUsageIncludes
Free$01 site10,000 pageviews/moPlacement and theme controls with basic compliance
Starter$29/mo or $290/yr3 sites100,000 pageviews/moCustom colors and six months of logs
Pro$79/mo or $790/yr10 sites500,000 pageviews/moLonger log retention, analytics, and branding controls
Agency$199/mo or $1,990/yrUnlimited sitesUnlimited pageviewsWhite-label oriented usage and priority scale

Plans

Annual billing

Every paid plan can bill monthly or yearly. Yearly billing charges ten months for twelve — two months free — and the interval is picked at checkout or on the dashboard billing page before you upgrade.

  • Starter, Pro, and Agency all offer both intervals; the plan capabilities are identical either way.
  • The dashboard billing page shows monthly and yearly prices side by side, with the yearly discount called out.

Plans

Pageview limits and overage

Plans are metered by the number of pageviews where the widget loads, counted per calendar month in UTC: 10,000 on Free, 100,000 on Starter, 500,000 on Pro, and unlimited on Agency.

  • The widget pings the API once per pageview, and counters reset automatically when a new month starts.
  • Usage meters on the site and billing pages show current consumption next to the plan limit.
  • Crossing the limit surfaces a warning banner in the dashboard with a direct upgrade path.

The banner never stops working

Going over the pageview limit never disables the widget. Consent collection and enforcement keep running for your visitors while you decide whether to upgrade.

Resources

Free tools

Two free utilities are available without an account, whether or not you use the paid platform.

Cookie scanner

Scan any public URL to inventory the cookies and trackers it sets before you install anything. Open the scanner

Cookie policy generator

Generate a cookie policy that matches what your site actually uses. Open the generator

Support

Troubleshooting and FAQ

The widget is not loading.

Confirm the script is reachable, the Site ID matches the dashboard, and the browser is not blocking widget.consentkit.us. Add data-debug to the script tag and reload.

The wrong regional UI is showing.

Use debug mode to inspect the detected country and state. VPNs, corporate proxies, and local development can affect geolocation signals.

Consent records are not appearing.

Check the browser network tab for POST /api/v1/consent/record. The request must include a real Site ID and come from a registered domain when Origin or Referer is present.

Google tags still fire too early.

Load ConsentKit during Consent Initialization in GTM and set denied defaults before analytics or advertising tags run.

Can I use ConsentKit with WordPress, Shopify, Webflow, or Next.js?

Yes. Install the script in the platform head area, theme layout, GTM container, or root application layout.

Service status

Something looks down? Check live uptime and incident history at status.consentkit.us.

Legal disclaimer

ConsentKit provides technical consent tooling and operational records. Privacy laws are complex and change over time. Work with qualified counsel to confirm your obligations.