---

name: posthog-install-auth description: | Install an official PostHog SDK and configure the correct project token, regional host, and server-only credentials. Use when bootstrapping or repairing SDK authentication. Trigger with "install PostHog", "configure PostHog", or "PostHog API key". argument-hint: "[project-path] [sdk] [region]" allowed-tools: Read, Write, Edit, Bash(npm:), Bash(pip:), Grep version: 1.14.0 license: MIT author: Jeremy Longshore jeremy@intentsolutions.io tags:

• saas
• posthog
• api
• authentication compatibility: Designed for Claude Code

---

PostHog Install & Auth

Overview

Install PostHog SDKs and configure authentication. PostHog uses two key types: Project API Key (phc_...) for event capture (public, safe for frontend) and Personal API Key (phx_...) for private API endpoints (never expose to clients).

Prerequisites

• Node.js 20+ or Python 3.10+
• PostHog account at app.posthog.com
• Project API key from Project Settings > Project API Key
• Personal API key from Settings > Personal API Keys (for server-side admin)

Instructions

Tool discipline

Use Read to inspect the relevant configuration and implementation before proposing changes. Use Grep to locate initialization, capture, flag, and credential boundaries. Use Write only for a new, explicitly requested artifact inside the target project. Use Edit for minimal changes to existing project files after the evidence pass.

Step 1: Install the SDK

set -euo pipefail
# Browser SDK (posthog-js)
npm install posthog-js

# Node.js server SDK (posthog-node)
npm install posthog-node

# Python SDK
pip install posthog

Step 2: Configure Environment Variables

# .env (add to .gitignore — never commit)
NEXT_PUBLIC_POSTHOG_KEY=phc_your_project_api_key    # Safe for frontend
POSTHOG_HOST=https://us.i.posthog.com               # US Cloud (or eu.i.posthog.com)
POSTHOG_PERSONAL_API_KEY=phx_your_personal_key      # Server-only, never expose
POSTHOG_FEATURE_FLAGS_SECURE_API_KEY=your_project_specific_secure_key # Server-side only
POSTHOG_PROJECT_ID=12345                             # From project URL

Step 3: Initialize Browser SDK (posthog-js)

// lib/posthog.ts
import posthog from 'posthog-js';

export function initPostHog() {
  if (typeof window === 'undefined') return;

  posthog.init(process.env.NEXT_PUBLIC_POSTHOG_KEY!, {
    api_host: process.env.NEXT_PUBLIC_POSTHOG_HOST || 'https://us.i.posthog.com',
    capture_pageview: true,        // Auto-capture $pageview
    capture_pageleave: true,       // Auto-capture $pageleave
    autocapture: true,             // Auto-capture clicks, inputs, form submits
    persistence: 'localStorage+cookie',
    loaded: (ph) => {
      if (process.env.NODE_ENV === 'development') {
        ph.debug();  // Logs all events to console
      }
    },
  });
}

Step 4: Initialize Server SDK (posthog-node)

// lib/posthog-server.ts
import { PostHog } from 'posthog-node';

let client: PostHog | null = null;

export function getPostHog(): PostHog {
  if (!client) {
    client = new PostHog(process.env.NEXT_PUBLIC_POSTHOG_KEY!, {
      host: process.env.POSTHOG_HOST || 'https://us.i.posthog.com',
      flushAt: 20,           // Send batch when 20 events queued
      flushInterval: 10000,  // Or every 10 seconds
      // The option name is retained by the SDK; pass the feature flags secure API key.
      personalApiKey: process.env.POSTHOG_FEATURE_FLAGS_SECURE_API_KEY,
    });
  }
  return client;
}

// CRITICAL: Flush before process exits (especially in serverless)
export async function shutdownPostHog() {
  if (client) {
    await client.shutdown();
    client = null;
  }
}

Step 5: Initialize Python SDK

import posthog
import os

posthog.project_api_key = os.getenv('NEXT_PUBLIC_POSTHOG_KEY')
posthog.host = os.getenv('POSTHOG_HOST', 'https://us.i.posthog.com')
posthog.personal_api_key = os.getenv('POSTHOG_FEATURE_FLAGS_SECURE_API_KEY')
posthog.debug = os.getenv('NODE_ENV') == 'development'

# Capture an event
posthog.capture('user-123', 'my_event', {'property_key': 'value'})

Step 6: Verify Connection

import { getPostHog } from './posthog-server';

async function verifyPostHog() {
  const ph = getPostHog();
  ph.capture({
    distinctId: 'test-setup',
    event: 'posthog_setup_verified',
    properties: { source: 'install-auth-skill' },
  });
  await ph.flush();
  console.log('PostHog event sent — check Activity tab in app.posthog.com');
}

verifyPostHog();

API Key Reference

Key Type	Prefix	Use	Expose to Client?
Project API Key	phc_	Capture events, evaluate flags	Yes (public)
Personal API Key	phx_	Private API scripts and HogQL queries	Never
Feature Flags Secure API Key	project-specific secret	Server-side local flag evaluation	Never

API Hosts

Region	Ingest Host	App Host
US Cloud	https://us.i.posthog.com	https://us.posthog.com
EU Cloud	https://eu.i.posthog.com	https://eu.posthog.com
Self-hosted	Your domain	Your domain

Error Handling

Error	Cause	Solution
posthog.init ignored	Called server-side	Guard with typeof window !== 'undefined'
Events not appearing	Wrong API key prefix	Use phc_ project key for capture
401 Unauthorized on API	Personal key expired/missing	Generate new key in Settings > Personal API Keys
ECONNREFUSED	Wrong host URL	Verify US vs EU region in api_host
Module not found	SDK not installed	Run npm install posthog-js or npm install posthog-node

Output

• Installed PostHog SDK(s) in node_modules or site-packages
• .env file with project and personal API keys
• Initialization code for browser and/or server
• Verified event delivery to PostHog dashboard

Examples

For a Node service, install posthog-node, initialize one long-lived client with the project token and regional ingest host, and add a shutdown path. Add a feature-flags secure key only for server-side local evaluation; use a scoped personal key, project secret key where available, or OAuth for private API calls.

Resources

See official PostHog references for current authority and verification boundaries.

• PostHog API Overview
• posthog-js Documentation
• posthog-node Documentation
• PostHog Python SDK

Next Steps

After setup, proceed to posthog-hello-world for your first event capture.