Scout - Klaviyo OAuth App Overview & Testing Instructions

For the Klaviyo Partner Portal review team. Support contact: steven@askscout.app.

OAuth App Overview

Scout is a weekly client-reporting tool for performance agencies. Agencies connect their clients’ marketing platforms - Klaviyo, Shopify, Meta Ads, Google Search Console, GA4 - and Scout drafts the Monday client report through Claude (Anthropic’s assistant) using real numbers from those platforms.

The Klaviyo integration is read-only. Scout never creates, edits, or deletes anything in Klaviyo. The granted scopes are all :read.

Customer Workflow

The steps an agency takes to set up and use the Klaviyo integration.

  1. Sign in to Scout at dashboard.askscout.app and create a workspace for the agency.
  2. Add a client from the Clients list (or via the onboarding wizard at /clients/new). Set the client’s scope (services managed) and KPI (free-text success definition - e.g. “grow attributed email revenue”).
  3. Connect Klaviyo on the Integrations step of the wizard (or later from the client detail page → Integrations tab). Click Connect next to Klaviyo, complete the OAuth handshake on Klaviyo’s side, and the card flips to Connected. Scout queues the initial 90-day sync automatically and re-syncs every 4 hours thereafter.
  4. Draft a report through Claude. From Settings → Connect to Claude, copy Scout’s MCP endpoint URL into Claude’s integrations page. Then in any Claude conversation, ask “Draft the Monday report for [client name]” - Claude calls Scout’s tools, assembles Klaviyo + Shopify + Meta + GSC + GA4 data, and produces a draft. Edit it in Claude, then ask Scout to publish or email it to the client.

Integration Details

Use cases and the corresponding Klaviyo API endpoints Scout calls.

Use caseEndpoint(s)
Account metadata - read the connected Klaviyo account’s timezone, currency, and account name so reports show the right numbers in the right units.GET /api/accounts/
Campaign performance - list the agency’s campaigns and pull per-campaign performance (sent, opens, clicks, attributed revenue) for the report period.GET /api/campaigns/
POST /api/campaign-values-reports/
Flow performance - list flows and pull per-flow weekly metrics (opens, clicks, attributed revenue) so the report can call out top-performing flows and flag drops.GET /api/flows/
POST /api/flow-values-reports/
List growth - list the agency’s lists and read the aggregate profile_count attribute for each, so the report can comment on net subscriber growth. Scout never reads individual profile records.GET /api/lists/
Metric definitions - discover the conversion metric ID Klaviyo uses for the account (required input for the campaign- and flow-values reports above).GET /api/metrics/

OAuth scopes requested: accounts:read, campaigns:read, flows:read, lists:read, metrics:read. Each scope maps directly to a use case above; Scout does not request any scope it does not call.

Architectural Diagram

How data flows between Klaviyo and Scout:

┌──────────────────────────────────────────────────────────────────────┐
│                       Agency user (browser)                          │
│            dashboard.askscout.app  ↔  claude.ai                      │
└──────────┬─────────────────────────────────────────────┬─────────────┘
           │                                             │
           │ "Connect Klaviyo"                           │ "Draft report"
           ▼                                             ▼
┌──────────────────────────┐              ┌─────────────────────────────┐
│   OAuth handshake        │              │     Scout MCP endpoint      │
│   (browser → Klaviyo)    │              │  /api/mcp on Vercel         │
│                          │              │  Bearer token validated     │
│   Redirects through      │              │  Rate limited per token     │
│   Nango token broker     │              └────────────┬────────────────┘
│   (api.nango.dev)        │                           │
└──────────┬───────────────┘                           │
           │                                            │
           │ Encrypted access token                    │ Calls tools that
           │ (forwarded to Scout immediately)          │ read synced data
           ▼                                            ▼
┌──────────────────────────────────────────────────────────────────────┐
│                       Supabase (Postgres)                            │
│   • integrations table - OAuth tokens encrypted at rest (Vault)      │
│   • klaviyo_campaigns, klaviyo_flows, klaviyo_lists, metrics tables  │
│   • Row-level security: every row keyed to (workspace_id, client_id) │
└──────────────┬───────────────────────────────────────────────────────┘
               │
               │ Background sync every 4 hours
               │ (server-side, never from browser)
               ▼
┌──────────────────────────────────────────────────────────────────────┐
│                          Klaviyo API                                 │
│   GET  /api/accounts/                                                │
│   GET  /api/campaigns/         POST /api/campaign-values-reports/    │
│   GET  /api/flows/             POST /api/flow-values-reports/        │
│   GET  /api/lists/                                                   │
│   GET  /api/metrics/                                                 │
│                                                                      │
│   READ ONLY - no write endpoints called, ever.                       │
└──────────────────────────────────────────────────────────────────────┘

Key points:

  • OAuth tokens are stored encrypted at rest in Supabase Vault, accessed via a restricted view by Scout’s server-side code only.
  • Klaviyo API calls are made server-side, never from the browser. The agency’s browser never sees the OAuth token.
  • Synced data is stored under the agency’s workspace_id and the client’s client_id, with Postgres row-level security enforcing tenant isolation as a second layer.
  • Scout passes the synced data to Claude (Anthropic’s API) only when an agency user invokes a draft. Anthropic’s commercial terms prohibit using customer inputs to train Anthropic’s models.

Product Integration Demo

A recorded walkthrough of the Klaviyo connection, sync, and a Klaviyo-driven report draft is available on request. Email steven@askscout.app and we will send a private link to the recording (Loom or YouTube unlisted).

Testing Details

We have provisioned a Scout test workspace with a Klaviyo sandbox account already connected and 90 days of representative campaign and flow data synced. To grant the Klaviyo review team end-to-end access:

  1. We will add app.marketplace@klaviyo.com to the Scout test workspace as a member, or
  2. We will trigger a password-reset email to the test account and share the email address with the review team so they can complete the reset themselves and sign in.

In line with Klaviyo’s guidance, we will not share account credentials in this document or via email. Email steven@askscout.app to confirm which approach you prefer and we’ll provision access immediately.

Once signed in, the review team can complete the Customer Workflow steps above end-to-end against the live Klaviyo sandbox, including disconnect / re-connect to verify revoke behaviour from both sides.

Quick reference