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). The workflow below is the high-level path; the verbatim code for every step lives in the full implementation walkthrough, and copy-paste sequences live in worked examples.
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
The full sequence is five steps. The essentials are below; drill into
references/implementation.md for the complete
code of each step (verify script, revision header, Python setup, scope table).
Step 1: Install the Official SDK
npm 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
Store the private key in .env and confirm it is gitignored. 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
import { ApiKeySession, ProfilesApi, EventsApi, ListsApi } from 'klaviyo-api';
const session = new ApiKeySession(process.env.KLAVIYO_PRIVATE_KEY!);
export const profilesApi = new ProfilesApi(session);
export const eventsApi = new EventsApi(session);
export const listsApi = new ListsApi(session);
Steps 4-5: Verify & set the revision header
Run a one-time verification against AccountsApi.getAccounts() to prove the key
works, and remember every request needs a revision: 2024-10-15 header (the SDK
adds it automatically; raw HTTP does not). Full verify script + cURL smoke test:
references/implementation.md.
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
| 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 |
Examples
Four copy-paste sequences (fresh Node project, key verification, Python with
retry tuning, raw-HTTP smoke test) are in
references/examples.md. The fastest sanity check —
confirm a key from a shell before writing any code:
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"
A 200 with a JSON data array means the key and revision header are valid; a
401 means the key is wrong; a 403 means it lacks the profiles:read scope.
Resources
Next Steps
After successful auth, proceed to the klaviyo-hello-world skill for your first
profile + event API call, then klaviyo-rate-limits to harden request handling
against the 75 req/s burst ceiling.
