Klaviyo Install Auth
Apps & Automationklaviyo-install-authKlaviyo 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".
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
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 anApiKeySession.
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-apipackage installed innode_modules.envfile withKLAVIYO_PRIVATE_KEYset- Verified API connection with account name printed
- Per-resource API clients ready for import
Error Handling
| Error | Status | Cause | Solution |
|---|---|---|---|
Authentication failed | 401 | Invalid or expired private key | Regenerate key at Settings > API Keys |
Forbidden | 403 | Key missing required scopes | Create key with appropriate scopes (e.g., profiles:read) |
Rate limited | 429 | Exceeded 75 req/s burst or 700 req/min steady | Honor Retry-After header; see klaviyo-rate-limits |
MODULE_NOT_FOUND | N/A | Wrong package name | Use klaviyo-api, not @klaviyo/sdk |
ENOTFOUND a.klaviyo.com | N/A | DNS/network failure | Check 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
| Scope | Required For |
|---|---|
profiles:read / profiles:write | Create/read/update profiles |
events:read / events:write | Track events, query metrics |
lists:read / lists:write | Manage lists, subscribe profiles |
segments:read | Query segments and members |
campaigns:read / campaigns:write | Create and send campaigns |
flows:read / flows:write | Manage flow actions |
templates:read / templates:write | Create/edit email templates |
data-privacy:write | GDPR/CCPA deletion requests |
Resources
Next Steps
After successful auth, proceed to klaviyo-hello-world for your first profile + event API call.