​

Web SDK and the public-key identify/track model

​

Two public surfaces, two different contracts

​

Why a public key (pk_) is safe to ship in browser JS

1. Read-only scopes. Public keys are created with read scopes only; the platform rejects a write or administrative scope on a pk at creation. A leaked public key can never reach the messaging, billing, or admin surfaces that a secret key (dv_live_sk_) unlocks. See Authentication and session model.
2. Writes confined to a narrow band. The only write endpoints a public key can reach are POST /sdk/identify, POST /sdk/track, and POST /sdk/in-app/events — and all three write into the key’s own tenant schema, nothing else. A leaked pk lets someone push behavior events or identification calls into your own audience data, which is spam-class abuse bounded by rate limits (below), not a credential for reading or mutating your account.
3. Hash-stored, revocation-checked. The platform stores sha256(key), never the plaintext, and every request re-checks that the key is active, unrevoked, unexpired, and — critically — of type public. A secret key with an altered prefix cannot authenticate the SDK surface; a key belonging to a deleted organization stops resolving immediately.
4. No version prefix in the URL. The /sdk/* routes mount on the root host, not under /api/v1, so your embed URL is stable across API versions: https://api.orbit.devotel.io/sdk/track never needs re-embedding when /api/v2 arrives. Pixel and redirect URLs live at the root for the same reason — the path a customer site embeds is a contract, and version churn belongs to the authenticated API.

POST /sdk/track HTTP/1.1
Host: api.orbit.devotel.io
X-API-Key: dv_live_pk_8dQ…
Content-Type: application/json

{
  "anonymous_id": "anon_wK3p2m",
  "events": [
    { "name": "checkout_started", "properties": { "cart_total_cents": 14999 } }
  ]
}

​

Stitching: how identify reconciles an anonymous visitor

POST /sdk/identify HTTP/1.1
X-API-Key: dv_live_pk_8dQ…

{ "anonymous_id": "anon_wK3p2m", "email": "ada@example.com", "display_name": "Ada Lovelace" }

HTTP/1.1 200 OK

{ "data": { "contact_id": "contact_9fMRA", "anonymous_id": "anon_wK3p2m" } }

1. Resolve or create the contact. Phone is the preferred arbiter (a phone can unlock messaging and voice); email is the fallback. An existing live contact with the identifier is updated in place; otherwise a new contact row is created. Idempotent by consequence: re-calling with the same pair returns the same contact.
2. Backfill the pre-identify funnel. Every event row captured under this anonymous_id gets its contact stamped, so the contact timeline in the dashboard shows the full journey the person actually traveled — anonymous browsing included — not just “first seen after they logged in.”
3. Record the surfaces the stitch unlocks. Web tracking is the immediate backfill. Messaging, voice, and video self-identify on the same phone or email the next time the person arrives through those channels — no further stitching call is needed, because each inbound channel keys resolution on the identifier it carries.

​

In-app events vs pixel events

• It is anonymous by design: the payload carries an anonymous_id (plus your optional host-app user id) and lands with a null contact, then rides the same identify backfill as track events.
• It writes to the same analytics sink as /sdk/track, so card engagement appears on the contact timeline next to site behavior rather than in a silo.
• Unlike a pixel, it is not attribution against a message send — an in-app surface is an owned channel with no carrier leg. “Delivery” is the SDK pulling the feed; the events endpoint only reports what the visitor did with it. See In-app channel model.

​

Security envelope

• CORS is global. The shared application plugin answers cross-origin requests from arbitrary origins — your visitors’ browsers call from your domain, not Orbit’s, so an origin allow-list would break the model. Origin is therefore not an authentication signal here; the key is.
• Per-IP rate limits. Both the public-keyed endpoints and the anonymous beacon fallback carry their own per-IP budgets, so a leaked pk degrades to bounded event-spam, not a flood.
• No PKCE, no Clerk. Those belong to dashboard sessions and OAuth flows. Browser embeds never perform a login handshake; identity arrives only through the explicit /sdk/identify call your site chooses to make.
• Payload discipline. Event property payloads are size-bounded and the whole body is schema-validated before a single write, so malformed or bloated batches get a 422, not a database row.

​

Common pitfalls

• Shipping a secret key in the bundle. A dv_live_sk_ key in client-side JavaScript hands account-level access to anyone who views source. Use the public key for all browser surfaces; secret keys stay on your server.
• Identifying on every page load. Identify once per session, when a strong identifier appears. Re-identification is idempotent, but it is wasted bandwidth; the backfill is a one-way stamp.
• Expecting stitching to merge two contact rows. Identify attributes the anonymous funnel to a resolved contact. When an operator later discovers the person duplicated across two rows, that consolidation belongs to the identity-resolution merge, under audit — the browser surface never collapses rows.
• Reading “no contact yet” as “no data yet”. Pre-identify events are stored with the anonymous id alone and get attached on identify. Reports filtered to known contacts simply don’t show the anonymous tail until stitching happens.

​

Cross-links

• Public pixels, redirects, and short links — the HMAC-signed public band this surface complements.
• Authentication and session model — public vs secret key forms and how resolution is decided.
• CDP event model — how tracked events flow into profiles, segments, and activation.
• CDP identity resolution — the operator-side merge for contacts already split across rows.
• In-app channel model — the owned channel behind /sdk/in-app/feed and its engagement events.
• Web SDK — installation, modules, and usage of @devotel-orbit/web.