OpenParable
Skip to content
← Back to skills

Klaviyo Install Auth

Apps & Automation
klaviyo-install-auth

Klaviyo Install Auth is an Agent Skill for apps & automation published in the jeremylongshore/claude-code-plugins-plus-skills repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Install and configure Klaviyo Node.js SDK with API key authentication. Use when setting up a new Klaviyo integration, configuring API keys, or initializing the klaviyo-api package in your project. Trigger with phrases like "install klaviyo", "setup klaviyo", "klaviyo auth", "configure klaviyo API key", "klaviyo SDK setup".

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/jeremylongshore/claude-code-plugins-plus-skills/blob/HEAD/plugins/saas-packs/klaviyo-pack/skills/klaviyo-install-auth/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/klaviyo-install-auth, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Klaviyo Install & Auth

Overview

Set up the official klaviyo-api Node.js SDK and configure private API key authentication against Klaviyo's REST API (revision 2024-10-15).

Prerequisites

  • Node.js 18+ (or Python 3.10+ for Python SDK)
  • Klaviyo account at https://www.klaviyo.com/
  • Private API key from Settings > API Keys in Klaviyo dashboard
  • Public API key (for client-side only -- never use in server code)

Instructions

Step 1: Install the Official SDK

# Node.js (official SDK -- NOT @klaviyo/sdk, that's deprecated)
npm install klaviyo-api

# Python
pip install klaviyo-api

Important: The npm package is klaviyo-api, not @klaviyo/sdk. The SDK exports per-resource API classes (ProfilesApi, EventsApi, etc.) that each take an ApiKeySession.

Step 2: Configure Authentication

# .env (NEVER commit to git)
KLAVIYO_PRIVATE_KEY=pk_***********************************
KLAVIYO_PUBLIC_KEY=UXxxXx    # Only for client-side endpoints

# .gitignore -- ensure secrets are excluded
echo '.env' >> .gitignore
echo '.env.local' >> .gitignore

Klaviyo uses two key types:

Key TypePrefixUse CaseHeader
Private API Keypk_Server-side REST APIAuthorization: Klaviyo-API-Key pk_***
Public API Key6-charClient-side Track/IdentifyQuery param company_id

Step 3: Initialize the SDK

// src/klaviyo/client.ts
import { ApiKeySession, ProfilesApi, EventsApi, ListsApi } from 'klaviyo-api';

// Create a session with your private API key
const session = new ApiKeySession(process.env.KLAVIYO_PRIVATE_KEY!);

// Instantiate per-resource API clients
export const profilesApi = new ProfilesApi(session);
export const eventsApi = new EventsApi(session);
export const listsApi = new ListsApi(session);

Step 4: Verify Connection

// src/klaviyo/verify.ts
import { ApiKeySession, AccountsApi } from 'klaviyo-api';

async function verifyKlaviyoConnection(): Promise<void> {
  const session = new ApiKeySession(process.env.KLAVIYO_PRIVATE_KEY!);
  const accountsApi = new AccountsApi(session);

  try {
    const accounts = await accountsApi.getAccounts();
    const account = accounts.body.data[0];
    console.log(`Connected to Klaviyo account: ${account.attributes.contactInformation.organizationName}`);
    console.log(`Account ID: ${account.id}`);
  } catch (error: any) {
    if (error.status === 401) {
      console.error('Invalid API key. Check KLAVIYO_PRIVATE_KEY in your .env file.');
    } else if (error.status === 403) {
      console.error('API key lacks required scopes. Generate a new key with full access.');
    } else {
      console.error(`Connection failed: ${error.status} ${error.message}`);
    }
    process.exit(1);
  }
}

verifyKlaviyoConnection();

Step 5: Set API Revision Header

All Klaviyo API requests require a revision header. The SDK handles this automatically, but if using raw HTTP:

# Direct cURL test
curl -X GET "https://a.klaviyo.com/api/profiles/" \
  -H "Authorization: Klaviyo-API-Key pk_***" \
  -H "revision: 2024-10-15" \
  -H "Accept: application/vnd.api+json"

Output

  • klaviyo-api package installed in node_modules
  • .env file with KLAVIYO_PRIVATE_KEY set
  • Verified API connection with account name printed
  • Per-resource API clients ready for import

Error Handling

ErrorStatusCauseSolution
Authentication failed401Invalid or expired private keyRegenerate key at Settings > API Keys
Forbidden403Key missing required scopesCreate key with appropriate scopes (e.g., profiles:read)
Rate limited429Exceeded 75 req/s burst or 700 req/min steadyHonor Retry-After header; see klaviyo-rate-limits
MODULE_NOT_FOUNDN/AWrong package nameUse klaviyo-api, not @klaviyo/sdk
ENOTFOUND a.klaviyo.comN/ADNS/network failureCheck internet connectivity, firewall rules

Python Setup

# pip install klaviyo-api
from klaviyo_api import KlaviyoAPI

klaviyo = KlaviyoAPI(
    api_key="pk_***",
    max_delay=60,   # Max retry delay in seconds
    max_retries=3   # Number of retries on 429/5xx
)

# Verify connection
accounts = klaviyo.Accounts.get_accounts()
print(f"Connected: {accounts['data'][0]['attributes']['contact_information']['organization_name']}")

API Scopes Reference

ScopeRequired For
profiles:read / profiles:writeCreate/read/update profiles
events:read / events:writeTrack events, query metrics
lists:read / lists:writeManage lists, subscribe profiles
segments:readQuery segments and members
campaigns:read / campaigns:writeCreate and send campaigns
flows:read / flows:writeManage flow actions
templates:read / templates:writeCreate/edit email templates
data-privacy:writeGDPR/CCPA deletion requests

Resources

Next Steps

After successful auth, proceed to klaviyo-hello-world for your first profile + event API call.