Skip to main content

Segment

Segment Integration Guide

Overview

This guide explains how to connect Bridged with Segment to collect, unify, and route customer data across your marketing and analytics stack. The integration supports reading customer profiles from Segment for activation, as well as sending engagement data back to Segment for use in other destinations.

Segment is a Customer Data Platform (CDP) that collects data from multiple sources, cleans and structures it, then routes it to over 400 destinations including analytics tools, data warehouses, and marketing platforms . Segment provides multiple API options including the Tracking API for real-time event collection and the Public API for workspace management .

Prerequisites

Before starting, ensure you have:

  • A Segment workspace with admin or source admin permissions

  • Your Segment Source Write Key (for sending data into Segment)

  • For reading data from Segment: A Public API token with appropriate scopes

  • Business tier plan if using OAuth 2.0 authentication (OAuth is only available on Business plans)

Connection Methods

Bridged supports three authentication methods for Segment:

Method

Best for

Setup complexity

Plan Requirement

Write Key (Tracking API - Preferred)

Sending events and customer data to Segment

Low

Any plan

Public API Token

Reading data from Segment (profiles, events)

Low

Any plan

OAuth 2.0

Multi-tenant apps, enhanced security

High

Business tier only

Recommendation: For most use cases, use Write Key authentication for sending data to Segment, and Public API Token for reading data from Segment. OAuth 2.0 is recommended only for Business tier customers requiring enhanced security or multi-tenant deployments .

Step 1: Obtain Your Segment Credentials

Option A: Source Write Key (For Sending Data to Segment)

The Write Key identifies your Segment source and is required for all Tracking API calls .

  1. Log in to your Segment workspace.

  2. Navigate to Connections → Sources.

  3. Select the source you want to connect to Bridged (or create a new source).

  4. Click on the source name to open its settings.

  5. Find your Write Key in the source settings panel .

  6. Copy and save the Write Key securely.

Important: Each Segment source has its own unique Write Key. You can regenerate the Write Key at any time from the source settings if it becomes compromised .

Option B: Public API Token (For Reading Data from Segment)

The Public API Token allows Bridged to read customer profiles, events, and other data from your Segment workspace.

  1. In your Segment workspace, navigate to Settings → Access Management .

  2. Click the Tokens tab.

  3. Click Create Token.

  4. Select Public API as the token type .

  5. Click Generate OAuth Secret .

  6. Copy and save the generated token immediately — you won't be able to see it again.

API URLs by Region:

Region

API URL

US-based workspaces

https://api.segmentapis.com

EU-based workspaces

https://eu1.api.segmentapis.com

Option C: OAuth 2.0 (Business Tier Only)

For Business tier customers, OAuth 2.0 provides enhanced security using JWT tokens .

Step 1: Create an OAuth App

  1. Navigate to Settings → Workspace settings → Access Management .

  2. Select the OAuth application tab.

  3. Click Create OAuth app.

  4. Enter the configuration:

    • Application name: Bridged Integration

    • Public key: Upload a public key in PEM format

    • Public key name: Bridged Key

    • Token expiration period: Select as needed (1 day to 30 days)

    • Scope: Select required scopes (e.g., tracking_api:write, public_api:read_write)

  5. Click Create.

Step 2: Connect a Source to OAuth

  1. Navigate to Connections → Sources.

  2. Select the source you want to use.

  3. Go to the Settings tab and select OAuth app.

  4. Click Connect OAuth app and select your OAuth app .

Step 3: Obtain Access Token

Bridged handles the JWT generation and token exchange automatically. The access token is obtained by:

  1. Creating a JWT with RS256 signing using your private key

  2. Sending a POST request to the regional authorization server (https://oauth2.segment.io for US, https://oauth2.eu1.segmentapis.com for EU)

  3. Receiving an access token valid for the configured expiration period

Important: Access tokens are only valid within the region where they were created .

Step 2: Configure Bridged to Connect to Segment

  1. Log in to your Bridged dashboard.

  2. Navigate to the Integrations section. If you do not see this section, contact support@bridged.media.

  3. Click Segment → Connect Account.

  4. Choose your authentication method:

Option A: Write Key (For Sending Data)

Field

Description

Where to find

Write Key

Your Segment source Write Key

Connections → Sources → [Your Source] → Settings

API Region

US or EU

Based on your workspace region

Option B: Public API Token (For Reading Data)

Field

Description

Where to find

Public API Token

Your Segment Public API token

Settings → Access Management → Tokens

API URL

Region-specific API endpoint

US: api.segmentapis.com, EU: eu1.api.segmentapis.com

Option C: OAuth 2.0 (Business Tier)

Field

Description

Where to find

Client ID

OAuth application ID

OAuth app → Overview tab → App ID

Private Key

Your PEM private key

Generated locally

Key ID (KID)

Public key identifier

OAuth app → Overview tab → Key ID

Region

US or EU

Based on your workspace

Write Key

Source Write Key

Source settings

Step 3: Configure Sync Settings

Once connected, configure the following:

Setting

Options

Description

Sync direction

Send only (Bridged → Segment), Receive only (Segment → Bridged), Both

Define data flow

Event types

Track, Identify, Page, Screen, Group

Which event types to sync

Data freshness

Real-time, Batch (hourly/daily)

How often to sync

Profile sync

Enabled, Disabled

Sync customer profiles from Segment

Bulk sync limit: Each bulk operation is limited to 50 records per request.

Step 4: Sending Data to Segment (Bridged → Segment)

Bridged uses the Segment Tracking API to send customer events and profile data to Segment .

Authentication for Sending Data

When sending data to Segment, Bridged uses the Write Key for authentication. The Write Key can be sent in two ways :

In the request body (simplest):

json

{
  "userId": "123",
  "event": "Lead Qualified",
  "writeKey": "YOUR_WRITE_KEY"
}

Basic Authentication (recommended):

  • Username: Write Key

  • Password: (empty)

  • Header: Authorization: Basic <base64(writeKey:)>

Event Types Supported

Event Type

Purpose

Example

Identify

Tie a user to their actions

User logs in, profile updated

Track

Record user actions

Button clicked, purchase completed

Page

Record page views

Homepage viewed

Screen

Record mobile screen views

Settings screen opened

Group

Associate users with groups

User added to organization

Example: Sending a Track Event

When a lead is qualified in Bridged, the following Track event is sent to Segment:

bash

POST https://api.segment.io/v1/track
Authorization: Basic <base64(writeKey:)>
Content-Type: application/json

{
  "userId": "lead_12345",
  "event": "Lead Qualified",
  "properties": {
    "score": 85,
    "source": "WhatsApp",
    "campaign": "Spring Sale 2026"
  },
  "timestamp": "2026-04-19T10:00:00Z"
}

Step 5: Receiving Data from Segment (Segment → Bridged)

For receiving data from Segment, Bridged can act as a destination that accepts inbound webhook requests from Segment .

Webhook Configuration

Segment sends data to Bridged via HTTPS POST requests. To configure this:

  1. In your Segment workspace, navigate to Connections → Destinations.

  2. Click Add Destination.

  3. Search for and select Webhook (or create a custom destination).

  4. Configure the destination:

    • Webhook URL: https://gateway.bridged.media/webhooks/segment

    • Authentication: Segment sends your Bridged API key in the Authorization header

Headers Sent by Segment

Segment includes the following headers with each request :

Header

Description

Authorization

Basic auth with your API key as username (password empty)

Content-Type

application/json

X-Segment-Settings

Base64-encoded custom settings

User-Agent

Segment.io/1.0

Webhook Authentication

To verify that requests are coming from Segment, Bridged checks the Authorization header:

  • The username field contains your Bridged API key (provided during setup)

  • The password field is empty

  • The string is Base64-encoded with the format Basic <base64(api_key:)>

Step 6: Test the Integration

  1. In Bridged, go to Integrations → Segment → Test Connection.

  2. For send direction: Create a test event in Bridged and verify it appears in your Segment debugger.

  3. For receive direction: Send a test event from Segment using the Segment Tracking API and verify it appears in Bridged.

Testing with cURL (Send to Segment)

bash

curl -X POST "https://api.segment.io/v1/track" \
  -H "Authorization: Basic $(echo -n 'YOUR_WRITE_KEY:' | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "test_user_123",
    "event": "Integration Test",
    "properties": {
      "test": true,
      "timestamp": "2026-04-19T10:00:00Z"
    }
  }'

Verifying Data in Segment

  1. Log in to your Segment workspace.

  2. Navigate to Connections → Sources → your source.

  3. Click the Debugger tab to see incoming events in real-time .

Common Use Cases

Playbook

Direction

Description

Activation

Send

Send lead qualification events to Segment for routing to marketing tools

Qualification Agent

Receive

Read customer engagement history from Segment for lead scoring

Nurture & Conversion

Both

Sync conversation outcomes to Segment; read customer 360 data from Segment

Analytics

Send

Track user interactions across WhatsApp and web for analysis in Segment destinations

Rate Limiting & Performance

  • Rate limits depend on your Segment plan, not on Bridged

  • Tracking API: Segment accepts high throughput but may throttle excessive requests

  • Public API: Rate limits vary by endpoint and plan

  • Bulk operations: Maximum 50 records per request

Security & Permissions

  • Write Key: Can be regenerated at any time; treat as sensitive

  • Public API Token: Store securely; used for read operations

  • OAuth 2.0: JWT tokens are short-lived (less than 60 seconds)

  • All API calls are made over TLS 1.2+

  • Access can be revoked at any time by deleting tokens or OAuth apps

Required Permissions by Role

Segment Role

Can use Write Key

Can create Public API Token

Can use OAuth

Workspace Owner

✓

✓

✓

Workspace Member

✓

✓

✗

Source Admin

✓

✓

✓ (connect only)

Source Read-only

✓

✗

✗

Troubleshooting

Issue

Likely cause

Solution

Write key rejected

Invalid or expired Write Key

Regenerate Write Key in source settings

Public API token rejected

Wrong token type or region mismatch

Use Public API token (not Config API) and verify region

No data appears

Source not properly configured

Check that source is active and events are visible in debugger

OAuth authentication fails

Missing Business tier

OAuth is only available on Business tier plans

Webhook not receiving data

Authorization header format incorrect

Verify Base64 encoding includes colon after Write Key

Rate limiting (429)

Too many API calls

Reduce sync frequency or upgrade Segment plan

"writeKey required" error

Write key missing from request

Include writeKey in body or Authorization header

EU region data not accessible

Using US API URL

Use eu1.api.segmentapis.com for EU workspaces

OAuth-Specific Issues

Issue

Likely cause

Solution

JWT invalid

Incorrect signing or payload

Verify algorithm is RS256 and claims are correct

Token expired

Expiration set too short

JWT must have expiration < 60 seconds

"kid" not found

Key ID mismatch

Verify Key ID from OAuth app Overview tab

Support

For integration support, contact your Bridged account manager or email support@bridged.media.