Security overview/Browser SDK
Browser SDK security
This page is for security, IT, and engineering teams evaluating how the FirstDistro browser SDK runs inside your product and what data moves between your users' browsers and FirstDistro.
Last updated: May 5, 2026
What the SDK does
The FirstDistro SDK is a small script your team adds to your web application. It sends product usage events (what you choose to track) to FirstDistro so features like customer health and insights reflect real behavior—not only CRM data.
You can install it via our npm package or a hosted install flow. Setup guidance lives in our Getting Started documentation.
What runs in the browser vs on FirstDistro
- In your users' browsers: the SDK loads, reads remote configuration, associates events with the user and account identifiers you provide, queues events, and sends them to FirstDistro over HTTPS.
- On FirstDistro servers: we receive those events, validate them, store them for your workspace, and use them for the product features you subscribe to—under the same tenant isolation and security practices described on our main Security page.
How the product connects (plain language)
When you use our recommended installation token, the SDK contacts FirstDistro over HTTPS to complete setup. Your app then uses that setup to load SDK settings and send batches of events to FirstDistro. Connections use TLS (encrypted in transit), consistent with our platform-wide data protection commitments.
For technical reviewers: configuration is fetched from /api/vendors/…/sdk-config using your workspace credentials after setup; events are sent to /api/tracking/events/batch.
Browser vs server credentials
Frontend and install-script flows use a publishable API key (prefix pk_live_). It is scoped to loading SDK configuration and sending usage events from the browser—not to full vendor API access.
Secret keys (sk_live_) are for trusted servers, automation, and MCP. They must not be embedded in pages or shipped in client bundles. If you are reviewing CSP or XSS exposure, assume anything labeled publishable may appear in page context; treat secret keys as you would other long-lived bearer tokens.
HTTP errors you may see during integration
- 401 Unauthorized typically means the key was missing, malformed, or not recognized (wrong value or revoked).
- 403 Forbidden means authentication succeeded but this credential is not allowed on that route or method—for example, using a publishable key on an endpoint or method outside its browser allowlist (SDK config + browser ingest).
Your integration should map these differently: 401 often calls for checking rotation and copy/paste mistakes; 403 calls for checking which key type and which URL you wired in each environment.
What data typically leaves the user's device
Each event your code records can include a name, optional custom fields you supply, and technical context the SDK attaches automatically so we can understand usage in context. The FAQ below cross-references this table for ingest-related questions.
| Category | Examples |
|---|---|
| Event payload | Event name; optional properties object you pass to track(); timestamp; session identifier; user and account identifiers when you have called setup. |
| Automatic page context | Full page URL, path, referring page (if the browser provides one), browser user-agent string, screen width and height, and a timestamp for the context snapshot. |
Treat custom properties as your responsibility: do not send passwords, secrets, payment card data, government IDs, or other highly sensitive categories you would not put in application logs.
Optional storage in the browser
By default, the SDK may persist identifiers and traits you set (for example user and account context) in the browser's local storage so sessions feel consistent across visits. You can turn persistence off in SDK configuration if your policy calls for it.
A separate session identifier may be stored for the browser tab in session storage so we can group events for analytics. Exact keys are listed under Storage keys in the browser.
When the user leaves a page (unload)
Browsers limit what scripts can do when someone closes a tab. In those cases the SDK may use the browser's "best-effort" send path, which cannot always set the same headers as a normal request. Our server accepts a carefully scoped payload so events are not silently dropped. Your security team can inspect this behavior in the browser's network tools during integration testing. Details appear under Event ingest and beacons.
Why your own app security still matters
The SDK runs as part of your web pages. If malicious code can run inside your product (a class of issues often discussed under "cross-site scripting" or XSS), it may be able to access anything your legitimate scripts can access in that page context—including data your integration holds in memory for FirstDistro.
FirstDistro does not remove the need for secure engineering practices on your side: patching vulnerabilities, reviewing dependencies, and using browser security features (such as content security policies) where appropriate for your stack. Our platform security overview describes how we protect data once it reaches FirstDistro—see Security at FirstDistro.
Privacy and agreements
How we handle personal data at the platform level is described in our Privacy Policy. Enterprise customers can discuss data processing agreements and security questionnaires with our team using the contacts on our Security page.
What we're improving
We continue to refine how browser credentials are scoped and presented so security reviews are straightforward—without changing the fundamental fact that any in-page SDK depends on the host app staying safe. That includes clearer separation of publishable and server keys in the product UI, documentation like this page for HTTP semantics (401 vs 403), and release communications when credential classes change. Ask your FirstDistro contact for the latest roadmap detail if this is part of your procurement process.
Security review FAQ: Cross-origin (CORS) access
For IT and security questionnaires about how browser origins talk to FirstDistro.
Why does FirstDistro use broad cross-origin rules for the SDK? Your product runs on your own website domains. The SDK needs to call FirstDistro APIs from your users' browsers without you proxying every request through your own servers first. Today, our SDK-related HTTP responses therefore include Access-Control-Allow-Origin: * so those calls can succeed from whichever origin hosts your app.
Which methods and headers are involved? Event ingestion uses POST and preflight OPTIONS with allowed headers such as Content-Type and X-API-Key. Remote configuration fetches use GET (and related preflight) and may include conditional caching headers such as If-None-Match with exposed ETag where applicable.
What if our policy requires allowlisted origins only? Some enterprises want FirstDistro to answer only from a fixed list of their domains instead of a wildcard. That product control is on our roadmap; contact us if your procurement or security review depends on it so we can align on timing and design.
Security review FAQ: Event ingest and beacons
What reviewers see in network tools for batches and tab-close sends.
How are events sent in normal browsing? The SDK batches events and sends them with POST to /api/tracking/events/batch, typically with your workspace API key in the X-API-Key header. Payload fields match the overview table at What data typically leaves the user's device.
What happens on tab close or navigation? Browsers do not let scripts set all headers on the unload "beacon" path. In that situation the SDK may include the same API key material inside the JSON body so the request can still be authenticated—this is visible in DevTools and is expected for that browser constraint, not a hidden side channel.
Does FirstDistro still validate traffic server-side? Yes. Requests must present valid credentials for your workspace; invalid or abusive traffic is rejected at the API layer regardless of browser origin.
Security review FAQ: Storage keys in the browser
Exact keys your DLP or browser policies may scan for.
| Storage | Key | Purpose |
|---|---|---|
| localStorage | firstdistro_context | Anonymous id plus user/account identifiers and traits when persistence is enabled (can be disabled in SDK configuration). |
| sessionStorage | firstdistro_session_id | Session id for grouping events in the current tab. |
| localStorage | fd_debug_dismissed | Remembers if the SDK debug overlay was dismissed (only relevant when debug mode is used). |
Security review FAQ: Debug mode (?fd_debug=true)
When enabled, the SDK can surface integration details on the page.
How is it turned on? Adding fd_debug=true to the page query string enables the SDK's debug experience for that load (for example ?fd_debug=true).
What can appear on screen? Status, event counts, and context derived from how you called setup— for example user email or name from traits when you provided them, plus account identifiers. A link to your FirstDistro workspace area may be shown for quick verification.
Vendor guidance: treat debug as support and staging only. Do not ask end customers to browse with debug enabled in production, and avoid screenshots that could leak identifiers into ticketing systems you do not control.
Questions?
Email hello@firstdistro.com or continue to the full security overview.