Skills Development Install and Configure Klaviyo API SDK

Install and Configure Klaviyo API SDK

v20260423
klaviyo-install-auth
This skill guides you through installing and setting up the official Klaviyo SDK for both Node.js and Python. It covers essential steps including authenticating with a private API key, managing environment variables for secure credential storage, and initializing resource-specific API clients (e.g., Profiles, Events). Use this when building integrations that require programmatic access to Klaviyo's marketing data, such as tracking user events or managing contact profiles.
Get Skill
241 downloads
Overview

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 Type | Prefix | Use Case | Header |
|----------|--------|----------|--------|
| Private API Key | pk_ | Server-side REST API | Authorization: Klaviyo-API-Key pk_*** |
| Public API Key | 6-char | Client-side Track/Identify | Query 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.

Info
Category Development
Name klaviyo-install-auth
Version v20260423
Size 5.98KB
Updated At 2026-04-28
Language