customerio-install-auth

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: "install customer.io", "setup customer.io", "customer.io auth", "configure customer.io API key", "customer.io credentials".

Quality

83%

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Passed

No known issues

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

Next Steps

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

Repository: jeremylongshore/claude-code-plugins-plus-skills
Commit: 3a2d27d

Last updated: about 8 hours ago
Created: about 8 hours ago

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.