Kentro Pixel

Kentro's first-party, consent-aware event collector for your websites, Kentro GO landing pages and your own servers.

Kentro Pixel is Kentro's first-party, consent-aware event collection service: it receives events from your websites through a small browser SDK, from Kentro GO landing pages, and from your own servers through a signed server API. It validates every event against a shared taxonomy, applies each visitor's consent, and records the result for Kentro analytics, attribution, audiences and destination forwarding.

📘

Preview

Kentro Pixel v1 is in preview. The collector answers immediately; sessions, conversions, the consent record, attribution runs, audience refreshes, destination deliveries and privacy requests run afterwards in Kentro's background processor. See Processing and retention.

In this page

  • What Kentro Pixel does
  • What Kentro Pixel does not do
  • Hosts at a glance
  • Pixel in Kentro GO
  • Management API
  • Where to go next

What Kentro Pixel does

  • One collector for every source. Browser events (SDK), Kentro GO landing pages and server-to-server events (HMAC-signed) use the same envelope and the same event taxonomy.
  • Validated at the door. Every event is checked against the JSON Schema of its event name. Unknown names, names Kentro reserves for its own records, unlisted properties and floating-point money are rejected per event with a reason code; one bad event never rejects a batch.
  • Consent-aware. Every event carries a consent snapshot. Kentro applies the property's consent rules per purpose (analytics, marketing, functional) and Global Privacy Control, records events that lack the required consent as suppressed (stored minimized) instead of processing them, and checks the person's consent record again before anything is exported.
  • Private by default. Page URLs lose their fragment and every query parameter except utm_source, utm_medium, utm_campaign, utm_content, utm_term, utm_id and ad click ids. Raw click ids are kept only with marketing consent (otherwise only their SHA-256 hashes). Referrers are reduced to a host name. User agents are reduced to a device class and a bot flag; the full user agent is kept only on accepted events whose consent grants marketing. Raw email and phone values are replaced by SHA-256 hashes (a property can opt in to keeping lead details as entered, see Consent and privacy). A browser event sent from a page that matches one of the property's sensitive path patterns is discarded whole. Payloads that look like health data, secrets or card numbers are quarantined. The raw IP address is never stored; ingestion receipts keep a salted hash that rotates daily.
  • Exactly once. Accepted events are deduplicated on event_id per property for at least 14 days, so retries are safe. A suppressed or quarantined event does not use up its event_id, so a corrected or consented resend is accepted.

What Kentro Pixel does not do

  • No fingerprinting. The SDK uses a random first-party anonymous id and a random session id, both kept in memory until analytics consent (or functional storage you declare) allows storing them. Kentro does not combine browser or device attributes into an identifier.
  • No consent or ad-blocker bypass. Without the required consent an event is suppressed, not processed. If a visitor blocks the SDK or the collector, those visits are missing: Kentro does not model, estimate or fill them in, and analytics responses say so in their coverage notes.
  • No revenue truth from the browser. Orders, refunds, subscriptions and other revenue facts are authoritative only when they arrive from a server source (POST /v1/server/events). Browser copies such as commerce.order_placed are accepted as signals and flagged non-authoritative. Send commerce.order_paid from your backend; that is what revenue reporting trusts.
  • No identity claims from the browser. Browser events cannot set subject_ref or commerce_subject_ref themselves. A signed-in visitor is identified only through an identity token your server signs (see Identity tokens); any other claim is dropped and the event is recorded anonymously with IDENTITY_UNVERIFIED.

Hosts at a glance

WhatProductionStaging (testing)Authentication
Collector and browser SDKhttps://pixel.kentro.livehttps://pixel.kentro.devProperty public key, or HMAC server key
Management APIhttps://apis.kentro.live/pixel/v1/...https://apis.kentro.dev/pixel/v1/...Kentro authentication plus the pixel:read or pixel:manage permission
Kentro Email signup capture (used only by the SDK form command)https://t.kentro.emailhttps://t-stg.kentro.emailProperty public key and the origin allowlist

Examples in this category use the production hosts. To test against staging, swap .live for .dev: staging has its own properties, keys and data (see Environments).

Pixel in Kentro GO

Kentro GO has a Pixel entry in the navigation, visible to users with the pixel:read or pixel:manage permission. It has three tabs:

TabWhat it does
PropertiesCreates properties and opens the property page.
DestinationsCreates, tests and enables destinations, and shows their delivery history.
PrivacyFiles privacy requests and follows their progress.

The property page has the tabs Install, Domains, Keys, Debugger, Validate, Health and Settings. Pixel data feeds the Analytics and Audiences pages of Kentro GO. Every action in these screens also works through the management API below.

Management API

The management API accepts the same credentials as the other Kentro APIs on that host: Authorization: Bearer <access token> from Kentro authentication, or a Kentro API key (X-API-Key, or kentro-key with kentro-secret). See Authentication and API keys.

Your user or key also needs a Pixel permission: pixel:read for reads and pixel:manage for writes (pixel:manage includes reads; admin and pixel:* include both). Missing credentials answer 401 { "error": "Unauthorized" }. A missing permission answers 403 with "error": "Forbidden" and a message that names the permission in words: You need permission to view Kentro Pixel. Ask an administrator for access. on a read, You need permission to manage Kentro Pixel. Ask an administrator for access. on a write. Match on the status and error, not on the sentence.

Conventions:

  • JSON in and out. Errors are { "error", "message" } plus the fields named on each page; request validation failures are 400 Bad Request.
  • Lists paginate with limit (50 by default) and an opaque cursor, newest first, and answer { "items": [...], "nextCursor": ... }. nextCursor is null on the last page, and a cursor that did not come from the route answers 400 INVALID_CURSOR. Two lists are not paginated: GET /v1/properties answers { "properties": [...] } with the 200 newest properties, and GET /v1/destinations answers at most 200 items with "nextCursor": null.
  • Property routes use snake_case fields (allowed_origins, privacy_mode, public_key); the analytics, audience, destination and privacy routes use camelCase (propertyId, consentPurpose, subjectKeys).
  • Date ranges accept YYYY-MM-DD (whole UTC days, inclusive end) or ISO timestamps and are capped at 180 days.
RoutePermissionPurpose
GET /v1/properties, POST /v1/propertiesread, manageList or create properties (create returns the first public key).
GET /v1/properties/:id, PATCH /v1/properties/:idread, manageOne property with its domains and keys; update name, origins, settings, privacy mode or status.
POST /v1/properties/:id/domains, DELETE /v1/properties/:id/domains/:domainIdmanageRegister or remove a domain.
POST /v1/properties/:id/verifymanageVerify a domain (dns_txt, http_file or meta_tag).
POST /v1/properties/:id/keys, DELETE /v1/properties/:id/keys/:keyIdmanageCreate or revoke a public key.
POST /v1/properties/:id/server-keys, DELETE /v1/properties/:id/server-keys/:keyIdmanageCreate (secret shown once) or revoke a server key.
GET /v1/properties/:id/snippetreadThe install snippet and SDK URL.
GET /v1/event-schemasNone; Kentro authentication (no Pixel permission) adds your custom schemasBuiltin and custom event schemas, with reserved and deprecated names flagged.
POST /v1/event-schemas/validateKentro authentication, no Pixel permissionValidate envelopes without storing them (the collector host takes a property key instead).
GET /v1/events/debug?propertyId&limitreadThe newest recorded events (up to 50).
GET /v1/ingestion/health?propertyIdread24-hour counters, freshness and the last rejections.
GET /v1/analytics/overview?propertyId&from&toreadSessions, visitors, page views, events, outcome counts, authoritative versus observed conversions, top sources and campaigns, consent suppression rate, coverage notes.
POST /v1/analytics/funnelsreadOrdered step counts for 2 to 8 events within a window.
GET /v1/analytics/conversions?from&to&type&limit&cursorreadConversion facts and totals. type is one of the seven conversion types (see Events); any other value answers 400.
GET /v1/analytics/attribution?model&windowDays&from&toreadCredits per channel and campaign from the latest successful attribution run with that model and windowDays. When no such run exists, the answer is 200 with "status": "no_run" and empty rows.
POST /v1/analytics/attribution/runsmanageQueue an attribution run (first_touch, last_touch, linear, position_based).
GET /v1/analytics/journeys?subjectId or sessionIdreadThe accepted events of one person or session, in order.
GET /v1/analytics/data-quality?propertyId&from&toreadAccept rate, duplicate ratio, quarantine count, suppression rate, freshness lag.
GET, POST /v1/audiences; GET, PATCH, DELETE /v1/audiences/:idread, manageRule-based audiences over accepted, consented events. Rules may not name a reserved event or marketing.product_viewed, and conversion conditions accept only the seven conversion types; otherwise 400.
POST /v1/audiences/:id/estimatereadCount the members of the stored or a draft rule set with the consent check exports apply (count; compiledCount before consent; sampled above 10,000 matches). An event condition that more than 100,000 people satisfy answers 422 AUDIENCE_TOO_LARGE.
POST /v1/audiences/:id/syncmanageQueue a membership sync to the enabled destinations that take audience membership (see Destinations). Answers 409 GO_STOPPED while Kentro GO is stopped.
GET, POST /v1/destinations; GET, PATCH, DELETE /v1/destinations/:idread, manageDestinations, see Destinations.
POST /v1/destinations/:id/test, POST /v1/destinations/:id/sync, GET /v1/destinations/:id/deliveriesmanage, manage, readTest send (409 GO_STOPPED while Kentro GO is stopped), replay, delivery history.
POST /v1/privacy/requests, GET /v1/privacy/requests, GET /v1/privacy/requests/:id, POST /v1/privacy/requests/:id/resumemanagePrivacy requests, see Consent and privacy.

The audience routes serve Pixel audiences only. Kentro Email contact segments are managed in Kentro Email; their ids answer 404 here. Routes under /internal/ exist for Kentro's own services and are not reachable from the internet.

Where to go next