---
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
title: posthog-install-auth
canonical_url: https://skilld.dev/gh/jeremylongshore/tons-of-skills-marketplace/posthog-install-auth
last_updated: 2026-10-07T06:06:28.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [references/official-docs.md](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/posthog-install-auth/references/official-docs.md).
>
> If the user asked to install this Skill, run `npx skilld install jeremylongshore/tons-of-skills-marketplace/posthog-install-auth`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/posthog-install-auth`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/jeremylongshore/tons-of-skills-marketplace/posthog-install-auth) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/posthog-install-auth`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/posthog-install-auth --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/posthog-install-auth --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# 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](https://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

```bash
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

```bash
# .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)

```typescript
// 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)

```typescript
// 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

```python
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

```typescript
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](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/posthog-install-auth/references/official-docs.md) for current authority and verification boundaries.

- [PostHog API Overview](https://posthog.com/docs/api)
- [posthog-js Documentation](https://posthog.com/docs/libraries/js)
- [posthog-node Documentation](https://posthog.com/docs/libraries/node)
- [PostHog Python SDK](https://posthog.com/docs/libraries/python)

## Next Steps

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