Write a spec on non-browser dependent Liveramp sync (s2s API) #1245

Activity

1. jevansnyc

   self-assigned this

   on Oct 6, 2026
2. ChristianPavilonis commented on Oct 9, 2026

   

   ChristianPavilonis

   on Oct 9, 2026

   Last edited by ChristianPavilonis

   Collaborator

   More actions

   Native LiveRamp ATS resolution should not be added to the current foundation/Lockr PR or branch. This issue is still a specification task, not an implementation-ready story. No new native LiveRamp spec or runtime implementation has been added during this work.

   The current work has two proposed documents:

   • docs/superpowers/specs/2026-10-09-server-side-identity-foundation-design.md: shared identity architecture.
   • docs/superpowers/specs/2026-10-08-lockr-identity-capture-design.md: Lockr as the first capture consumer.

   These are working drafts, not shipped APIs or already available configuration. A later LiveRamp spec should depend on the foundation rather than extend the Lockr spec.

   Related context: #354, #355, #1054, #630 and #619. The existing browser integration is described in docs/superpowers/specs/2026-08-21-liveramp-integration-design.md. The decision that closed #630 as not planned must be reconciled before approving new hashed-email resolution work.

   1. The problem and the actual coverage goal

   The current LiveRamp path uses Prebid's managed identityLink module in the browser. The reported publisher test on 2026-10-06 found Safari blocking its request to api.rlcdn.com through tracking protection, without an HTTP status. The module then set _lr_retry_request=true for an hour, pbjs.getUserIds().idl_env remained null, and no envelope reached the auction. A control request to another identity host succeeded, pointing to host-level tracking protection rather than a general network failure. This is reported observation from the investigation, not a new live reproduction performed for this comment.

   The envelope is an opaque encrypted identity value for authorized demand partners. TS stores and forwards it; it does not decrypt it into a person's identity.

   Moving the request to the edge avoids depending on a browser request to the blocked host. It does not, by itself, give LiveRamp a way to recognize an anonymous visitor.

   The initial native path should target visitors for whom an approved identifier is available, on any browser. It cannot promise a RampID on every browser visit, a match for every supplied identifier, or anonymous Safari coverage. Estimate how often the publisher actually recognizes visitors before projecting coverage or revenue benefit. First-auction availability is also not guaranteed because resolution is intended to happen after the response is sent.

   2. What the hashed identifier means, and where it is documented

   A hashed email is a deterministic fingerprint calculated from a normalized email address. LiveRamp can compare that fingerprint against its own records. It is not an identifier TS can derive from ts-ec, IP address or user agent.

   LiveRamp's Step 4: Call the ATS Envelope API documents:

   • it=4: hashed email.
   • it=11: hashed phone number.
   • it=15: approved custom ID, passed as ANA_ID:CUSTOM_ID.
   • iv: "The hashed version of the raw email or phone number."
   • atype=3: server-to-server implementation.

   The identified-envelope reference explicitly says "Retrieve envelopes using (hashed) identifiers."

   Step 3: Prepare the Identifiers describes normalization before hashing, including whitespace removal, lowercasing, removing email plus suffixes and removing dots before @ for Gmail. Best Practices recommends SHA256 when only one email hash is supplied. The documentation also supports multiple email hash types; we have not decided to collect or send all of them. Phone and custom-ID support need their own agreed scope and provider checks.

   Hashing does not make the identifier anonymous. Someone with a candidate email can calculate its hash and compare it. Hashes remain sensitive inputs requiring consent, restricted handling, retention decisions and deletion rules.

   The publisher does have login/subscription/newsletter systems that know email addresses for some visitors. What remains unresolved is how an approved hash gets from those systems to TS, and when those systems can associate it with the current visitor.

   flowchart TD
       A[Publisher knows visitor email] --> B[Publisher normalizes and hashes it]
       B --> C[Approved trusted input reaches TS]
       C --> D[After-send ATS request with allowed consent]
       D --> E[LiveRamp returns an identity envelope if matched]
       E --> F[Shared identity service persists it under the existing EC]
       F --> G[Later auctions use the visible unexpired envelope]
   

   Loading

   This is a candidate flow, not an approved input contract.

   3. Correction: a cookie-recognition endpoint also exists

   The earlier issue outline's statement that there is no call without a hashed identifier was too broad.

   LiveRamp documents a cookieable-envelope endpoint, which says:

   Instead of using an identifier, the rlcdn.com cookie values are sent and used to perform resolution instead.

   It names rlas3 and pxrc as LiveRamp cookies. This documentation is within the ATS API documentation; we should not describe all cookie-based retrieval as an undocumented or necessarily separate RTIS-only protocol.

   That endpoint still requires a recognizable identity input, supplied by LiveRamp's cookie footprint instead of a hash. Those third-party cookies are not automatically sent to TS on the publisher domain. Server-side dispatch does not manufacture access to them or remove Safari's cookie restrictions. TS's ts-ec cookie is not a substitute for a LiveRamp cookie.

   Keep these cases separate:

   • Initial identified resolution from a hash or approved custom ID.
   • Recognition from existing LiveRamp third-party cookies, if an approved way to obtain them exists.
   • Refresh from an already acquired envelope.

   4. Options for communicating publisher identity to TS

   Option A: a private publisher-origin response header

   The first option to investigate is a private response header from the trusted publisher backend. On a request where the backend recognizes the visitor, it returns the page and an approved email hash. TS extracts the signal, removes the header, returns the page, and can use the hash during after-send work.

   This is a backend response signal, not a browser-supplied request header. It would be a new contract to implement. Merely naming a header such as X-ts-hem does not create that trust boundary.

   Requirements and questions:

   • Can the publisher backend add the header on relevant authenticated responses?
   • Accept it only from the configured trusted publisher origin, not arbitrary proxied integrations or browser input.
   • Remove browser-supplied copies before forwarding if they could be reflected by the origin.
   • Bind it to the existing full EC ID for the current request. It must not mint a root or nominate an unrelated visitor.
   • Strip it before the browser sees the response, including when consent denies resolution.
   • Do not put it in cached HTML templates, logs, traces, metrics or error messages.
   • Visitor-specific origin responses must not enter shared caches with another visitor's signal. If the page is otherwise publicly cached, use an appropriate private/bypass policy or a separate authenticated lookup.
   • Confirm hashing/normalization ownership, supported encoding, size limits and malformed-input behavior.

   This may be the simplest route because TS already proxies publisher responses, but publisher feasibility and cache behavior are unconfirmed.

   Option B: an authenticated publisher-backend API call

   The backend could notify TS on login, subscription or another approved identity event, sending the hash and the associated EC through an authenticated server-to-server endpoint.

   This supports event-driven systems but requires endpoint authentication, authorization, rate limits, replay handling and reliable visitor/EC association. A caller knowing an EC string must not thereby gain permission to attach arbitrary identity data. Publisher binding, logout and account-switch behavior need to be designed.

   No such identifier-intake endpoint is approved or implemented today. This is distinct from sending an already-resolved partner UID through existing sync APIs.

   Option C: a trusted upstream/CDN request signal

   A publisher-controlled layer in front of TS could provide a request header, but only with an authenticated or otherwise enforced trusted-hop contract. TS must distinguish that layer from the public client and strip or reject spoofed headers. A publisher origin behind TS cannot simply set a header on the browser request that TS has already received.

   A bare header convention is not sufficient.

   Option D: browser-obtained envelope reuse

   Keep the existing browser module as an optional source of already-resolved envelopes, submitted through the normal auction-body path and persisted under foundation rules.

   This can help visitors recognized by the browser module without a publisher hash. It is not a native hashed-identifier source and does not automatically make an envelope available to another browser.

   We have not selected an input option. An unauthenticated browser hash-submission endpoint should not be treated as equivalent to a trusted publisher signal.

   5. Identifier retention and privacy remain undecided

   The suggested starting point is request-scoped hash handling: keep the hash only for that request's permitted after-send work and persist only the resulting opaque envelope. This is a recommendation, not an approved decision.

   LiveRamp's refresh documentation confirms that refresh takes the existing envelope, not the original email hash. Retaining a hash is therefore not required for ordinary envelope refresh.

   However, after an envelope expires or becomes unusable, initial re-resolution requires an approved identifier again. If it is request-scoped and unavailable on that visit, TS must omit the ID until a new input arrives. A missed initial resolution also has no durable input to retry later.

   Persisting hashes could enable later re-resolution but adds a new sensitive-data store and requirements for retention, access control, purpose limitation, logout/account changes and DSR deletion. Do not add this silently to the partner-ID map.

   The later spec must decide whether TS ever sees plaintext identifiers. The preferred candidate is publisher-side normalization/hashing so TS receives no plaintext email, but that is not yet an approved publisher interface.

   6. Use the shared identity architecture

   The agreed direction is to standardize the lifecycle, not force every provider into the same HTTP protocol:

   • Integrations acquire and interpret identities.
   • A shared coordinator handles eligible after-send work, consent revalidation, request limits and transport safeguards.
   • EC owns validation, conditional mutation, source policy, expiry and auction delivery.
   • Lockr implements passive capture of proxied responses.
   • A later LiveRamp module implements active ATS resolution and refresh through optional integration capabilities.
   • Browser auction-body IDs remain conservative enrichment inputs, not authoritative provider updates.

   Provider protocol settings belong under [integrations.liveramp]. Generic source policy belongs under [[ec.partners]]. Do not put LiveRamp-specific placement/request fields into the shared EC partner type or add a private LiveRamp KV writer.

   The existing pull-sync implementation is not a ready-made ATS resolver. It sends ec_id with a bearer token, expects {"uid":"..."}, and only fills missing sources. It does not refresh existing UIDs. Reuse its execution/safety mechanisms, not its request/response or eligibility contract. The presence of a browser-supplied UID must not automatically prevent a permitted native resolution when the provider's input/binding policy requires one.

   The foundation draft proposes known expiry, trusted writer and revision metadata. Future refresh results and invalidation must be conditional on the record revision they used, so a stale request cannot overwrite or delete a newer envelope. Comparing UID alone is insufficient when a refresh changes expiry without changing the UID.

   7. Source ownership and config validation

   Decision: ownership of liveramp.com must be an explicit operator choice between Lockr capture and native LiveRamp resolution. Do not use registration order or silently switch owners after a failure.

   The foundation proposes a vendor-neutral identity_owner source policy. This is not an existing runtime config field yet. An integration can claim several sources; a source has one selected authoritative managed owner.

   Decision: validate ownership in config validate, config push and startup. Our current CLI already uses shared typed config validation hooks, so this is the appropriate place for deterministic checks.

   Validation should reject invalid ownership, a module that does not claim the source, conflicting authoritative legacy paths and malformed provider settings. Warnings can cover optional supplements or operational prerequisites that cannot be checked locally; a broken ownership contract should be an error, not just a warning.

   Ordinary config validation must not disclose an identifier to LiveRamp to test approval. It cannot prove actual placement enablement, approved origins or provider rate limits. Those require account-team confirmation and an explicit controlled live-validation step.

   8. Keeping the Chrome browser path

   Decision in principle: keep the browser identityLink module available as an optional supplement. It may recognize visitors whose publisher identifier is unavailable.

   It is not automatically harmless or free:

   • It still makes vendor requests and needs correct browser consent enforcement.
   • Browser updates must not replace authoritative native or Lockr-owned KV state.
   • Browser and server may return different envelope values. Define bidder-facing merge precedence separately from storage ownership; current body precedence does not automatically mean the operator's authoritative source wins an auction.
   • Supplement mode may still attempt a blocked request on Safari. Do not claim Chrome-only behavior without defining how that restriction is enforced.
   • Keep a native-only configuration for validation. The acceptance criterion "no browser request to api.rlcdn.com" applies to that configuration, not a mode that deliberately enables the supplement.

   We have not approved automatic browser detection or silently disabling existing publisher-owned Prebid configuration.

   9. Provider contract and prerequisites

   The published identified API uses GET /api/identity/v2/envelope. V2 can return multiple envelope products; select the regular ATS envelope with type=19 and source=envelopeLiveramp. Do not confuse it with ATS Direct segments, PAIR IDs or other envelope types. Decide whether V1 compatibility is actually needed rather than adding it automatically.

   The documented server-to-server request includes placement pid, identifier it/iv, atype=3, consent parameters, an approved Origin, and X-Forwarded-For carrying the actual end-user IP from trusted platform context. Do not forward an arbitrary client-supplied forwarding header or publisher cookies/credentials to the provider.

   The docs describe placement/origin approval rather than an API-key parameter. A Placement ID is an operator identifier, not a secret. Do not invent a secret-store requirement unless LiveRamp supplies an actual secret.

   None of the deployment prerequisites were confirmed in this discussion:

   • A placement approved and enabled for server-to-server calls.
   • Publisher production and test origins approved in its privacy review.
   • Approved serving countries and any additional country restrictions.
   • Fastly edge-egress/IP allowlisting requirements, if any.
   • Rate limits, concurrency limits, timeouts and retry expectations.
   • A usable test placement and test origin.
   • The custom namespace account ID if custom IDs are selected.

   These are rollout blockers, not facts inferred from having a browser Placement ID or valid local configuration.

   10. Consent and lifecycle rules

   The native spec must define global EC permission plus LiveRamp-specific consent before disclosure. The proposed GDPR policy requires TCF Purposes 1 and 4 and vendor 97, subject to confirmation of LiveRamp requirements and publisher CMP configuration. Do not describe it simply as "matching the browser path": the pinned Prebid defaults do not always require Purpose 4 for cookie-recognition resolution.

   For US traffic, map the applicable GPP string and section IDs, or the explicitly supported US Privacy path. Respect DNT and Sec-GPC before dispatch. Recheck the live consenting KV root immediately before the outbound call and reject tombstoned roots during write-back. An expired envelope is not permission to make another call.

   Step 5: Store the Identity Envelope With a Timestamp documents a 15-day envelope TTL for California and 30 days elsewhere. Step 7 recommends refresh on the first subsequent page load after authentication and again every 30 minutes of active page navigation/refresh, using it=19 and the envelope value. A successful refresh resets expiry and requires storing the new envelope/timestamp.

   The server design should be activity-driven after-send work, not a timer promised to run while a visitor is inactive. It needs last-successful-refresh/due-state and bounded failure/negative-cache policy; existing fill-missing pull sync is insufficient.

   Distinguish outcomes:

   • 200: parse and validate the intended envelope product.
   • Initial retrieval 204: no envelope. The documentation includes opt-out/no-positive-consent cases. Do not infer global EC withdrawal from every empty response.
   • Refresh 204: the documentation says an expired envelope must be discarded and a new one fetched through initial resolution. Invalidate only the matching old revision. Re-resolve only when approved input and current consent permit it, with no blind retry loop.
   • 400/401/403: configuration, parameter or approval failure; report redacted status, avoid repeated hammering, and do not erase a still-valid record merely because configuration broke.
   • 451: country/consent failure; do not bypass it with another input or endpoint.
   • Timeout/temporary failure: retain an otherwise valid envelope and retry only under bounded policy. Known-expired envelopes remain omitted.

   Consent withdrawal and DSR deletion must remove the relevant identity data and any retained resolution inputs/bindings. Define logout/account-switch behavior separately from global consent withdrawal.

   11. Delivery, safety and testing

   Use the existing EC ID and shared snapshot/mutation path. No new EID cookie and no native resolution on the organic hot path. Later auctions may miss an ID until the post-send write becomes visible.

   Emit liveramp.com with the configured OpenRTB atype=3, but verify the exact envelope representation expected by the pinned Prebid module and bidders. The browser storage docs show a Base64-encoded envelope wrapper; blindly storing a raw API field or double-encoding it can change the bidstream value. Check whether legacy ext.rtiPartner=idl compatibility is actually needed. Do not confuse ATS request atype with OpenRTB agent type merely because both use the value 3.

   Validate realistic envelope lengths against the shared 512-byte UID cap. Changes to caps, metadata or delivery representation need shared-contract review, not an ad hoc LiveRamp exemption. Do not use the one-year EC row TTL as the envelope TTL.

   Transport must have destination/redirect allowlisting, narrow header forwarding, timeouts, defined rate-limit identity scope, and independent limits on original response bytes and decoded JSON. Compressed input must not be fully expanded before checking its decoded limit. Never log hashes, envelopes, consent strings or provider URLs containing identity query parameters. Diagnostic EID headers are being retired by the foundation proposal, so validation should use controlled bidder-facing payload evidence, not depend on x-ts-eids.

   Tests should cover trusted input intake and cache/header stripping, hashing fixtures without real identifiers, consent matrices, request/header construction, response-product selection, expiry, same-UID refresh, stale-result races, withdrawal races, source ownership, browser/server precedence, bounded transport, errors, rate limits and metadata-preserving KV round-trips. Live tests must use approved test conditions and retain only redacted status/source/count evidence.

   The foundation's storage rollout also matters: older writers can strip lifecycle metadata, and older readers can ignore expiry. Complete metadata-compatible deployment before activation; disabling acquisition is not permission to roll back to a UID-only reader/writer.

   12. Cross-browser recognition is separate work

   Persisting an envelope in the Chrome visitor's EC row does not make it appear in Safari's row. The current full EC ID contains a random per-cookie suffix. A common IP-derived prefix is not proof that two browsers belong to the same person.

   The earlier harvest-and-propagate outline is therefore not an already available route to anonymous Safari coverage. Any cross-browser association needs an approved linking mechanism and its own privacy, consent and household/shared-IP rules. Keep it out of the first native ATS spec unless separately approved.

   Questions to answer before writing an implementation-ready spec

   • Which identifier types are in the first delivery: SHA256 email only, phone, or approved custom IDs?
   • Can the publisher produce normalized hashes and identify the current visitor without exposing plaintext to TS?
   • Which trusted communication option is feasible, and how is it authenticated/bound to the existing EC?
   • How do caching, origin responses and header stripping prevent cross-visitor disclosure?
   • Is the hash request-scoped or retained, and what are retention, deletion, logout and account-switch rules?
   • What happens after expiry or a missed initial write when no identifier is available again?
   • Which integration owns liveramp.com for each deployment, and how are conflicting legacy paths blocked?
   • Is the browser supplement enabled, and which envelope wins an auction when its value differs from KV?
   • How do native-only acceptance tests differ from supplement mode?
   • Has LiveRamp confirmed placement/origin/country approval, test access, edge-egress requirements and request limits?
   • What exact consent requirements and regional lifecycle rules apply to this placement?
   • What are the refresh schedule, error backoff, invalidation and re-resolution policies?
   • What envelope encoding, size and bidder metadata are required?
   • What foundation deployment/rollback gate must complete before activation?

   Suggested sequence: settle publisher input feasibility and LiveRamp approvals, then write the standalone LiveRamp integration spec against the shared foundation. Keep native resolution disabled until those decisions and live-validation prerequisites are satisfied. ATS Direct segments/GAM targeting, RTIS callbacks, sidecar decryption and cross-browser linking remain separate work.