customerio-install-auth

Customer.io Install & Auth

Overview

Set up the customerio-node SDK and configure authentication for Customer.io's two API surfaces: the Track API (identify users, track events) and the App API (transactional messages, broadcasts, data queries).

Prerequisites

• Node.js 18+ with npm/pnpm
• Customer.io account at https://fly.customer.io
• Site ID + Track API Key from Settings > Workspace Settings > API & Webhook Credentials
• App API Key (bearer token) from the same page — needed for transactional messages and broadcasts

Two API Keys, Two Clients

Client	Auth Method	Key Source	Use For
TrackClient	Basic Auth (Site ID + API Key)	Track API credentials	identify(), track(), trackAnonymous(), suppress(), destroy()
APIClient	Bearer Token (App API Key)	App API credentials	sendEmail(), sendPush(), triggerBroadcast()

Instructions

Step 1: Install the SDK

npm install customerio-node

The package exports TrackClient, APIClient, RegionUS, RegionEU, SendEmailRequest, and SendPushRequest.

Step 2: Configure Environment Variables

# .env — NEVER commit this file
CUSTOMERIO_SITE_ID=your-site-id-here
CUSTOMERIO_TRACK_API_KEY=your-track-api-key-here
CUSTOMERIO_APP_API_KEY=your-app-api-key-here
CUSTOMERIO_REGION=us          # "us" or "eu"

Add .env to .gitignore if not already there.

Step 3: Create the Track Client

// lib/customerio.ts
import { TrackClient, RegionUS, RegionEU } from "customerio-node";

function getRegion() {
  return process.env.CUSTOMERIO_REGION === "eu" ? RegionEU : RegionUS;
}

// Singleton — reuse across your app
let trackClient: TrackClient | null = null;

export function getTrackClient(): TrackClient {
  if (!trackClient) {
    const siteId = process.env.CUSTOMERIO_SITE_ID;
    const apiKey = process.env.CUSTOMERIO_TRACK_API_KEY;
    if (!siteId || !apiKey) {
      throw new Error(
        "Missing CUSTOMERIO_SITE_ID or CUSTOMERIO_TRACK_API_KEY"
      );
    }
    trackClient = new TrackClient(siteId, apiKey, { region: getRegion() });
  }
  return trackClient;
}

Step 4: Create the App API Client

// lib/customerio-app.ts
import { APIClient, RegionUS, RegionEU } from "customerio-node";

let appClient: APIClient | null = null;

export function getAppClient(): APIClient {
  if (!appClient) {
    const appKey = process.env.CUSTOMERIO_APP_API_KEY;
    if (!appKey) {
      throw new Error("Missing CUSTOMERIO_APP_API_KEY");
    }
    const region =
      process.env.CUSTOMERIO_REGION === "eu" ? RegionEU : RegionUS;
    appClient = new APIClient(appKey, { region });
  }
  return appClient;
}

Step 5: Verify Connection

// scripts/verify-customerio.ts
import { getTrackClient } from "../lib/customerio";

async function verify() {
  const cio = getTrackClient();
  try {
    // Identify a test user — if credentials are wrong, this throws
    await cio.identify("test-verify-user", {
      email: "verify@example.com",
      created_at: Math.floor(Date.now() / 1000),
    });
    console.log("Customer.io connection verified successfully");
    // Clean up: suppress the test user
    await cio.suppress("test-verify-user");
    console.log("Test user suppressed");
  } catch (err: any) {
    console.error("Connection failed:", err.statusCode, err.message);
    process.exit(1);
  }
}

verify();

Run with: npx tsx scripts/verify-customerio.ts

Region Configuration

Region	Track API Base URL	App API Base URL	SDK Constant
US	https://track.customer.io	https://api.customer.io	RegionUS
EU	https://track-eu.customer.io	https://api-eu.customer.io	RegionEU

Your region is set when you create your Customer.io account. Check Settings > Workspace Settings to confirm. EU accounts must specify RegionEU or all API calls will fail with 401.

Error Handling

Error	Cause	Solution
401 Unauthorized	Wrong Site ID or Track API Key	Verify both values in Customer.io Settings > API & Webhook Credentials
401 on App API	Wrong App API Key or using Track key	App API uses a different bearer token — check the App API key
Region mismatch	EU account using US endpoint	Set CUSTOMERIO_REGION=eu and use RegionEU
ENOTFOUND	DNS resolution failure	Check network, proxy, or firewall blocking track.customer.io
MODULE_NOT_FOUND	SDK not installed	Run npm install customerio-node

Security Notes

• Store credentials in a secrets manager (GCP Secret Manager, AWS SSM, Vault) for production
• Track API Key can identify/track users but cannot send messages — lower risk
• App API Key can send messages and access data — treat as highly sensitive
• Rotate keys every 90 days via Settings > API & Webhook Credentials > Regenerate

Resources

• Managing API Credentials
• Account Regions (US and EU)
• Track API Reference
• App API Reference
• customerio-node on GitHub

Next Steps

After successful auth, proceed to customerio-hello-world for your first identify + track call.