Install and configure Customer.io SDK/CLI authentication.
Use when setting up a new Customer.io integration, configuring API keys,
or initializing Customer.io in your project.
Trigger with phrases like "install customer.io", "setup customer.io",
"customer.io auth", "configure customer.io API key".
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).
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: "[email protected]",
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
