Apply PostHog security best practices for secrets and access control.
Use when securing API keys, implementing least privilege access,
or auditing PostHog security configuration.
Trigger with phrases like "posthog security", "posthog secrets",
"secure posthog", "posthog API key security".
Secure PostHog API key management, least-privilege access, and secret rotation. PostHog has two key types with very different security profiles: the Project API Key (phc_...) is intentionally public and safe to include in frontend bundles, while the Personal API Key (phx_...) grants admin access and must never be exposed.
Prerequisites
PostHog account with admin access
Understanding of environment variable management
.gitignore configured
Instructions
Step 1: Understand Key Security Profiles
Key Type
Prefix
Exposure Risk
Capabilities
Project API Key
phc_
Low (designed to be public)
Capture events, evaluate flags, identify users
Personal API Key
phx_
Critical (full admin access)
CRUD flags, read persons, query insights, delete data
# .env (NEVER commit)
NEXT_PUBLIC_POSTHOG_KEY=phc_abc123 # Safe for frontend (NEXT_PUBLIC_ prefix)
POSTHOG_PERSONAL_API_KEY=phx_xyz789 # Server-only — NEVER in frontend code
POSTHOG_PROJECT_ID=12345
# .gitignore
.env
.env.local
.env.*.local
Step 2: Create Scoped Personal API Keys
set -euo pipefail
# Create a read-only key for BI dashboards
curl -X POST "https://app.posthog.com/api/personal_api_keys/" \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"label": "bi-dashboard-readonly",
"scopes": ["insight:read", "dashboard:read", "query:read"]
}'
# Create a key scoped to feature flags only
curl -X POST "https://app.posthog.com/api/personal_api_keys/" \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"label": "feature-flag-service",
"scopes": ["feature_flag:read", "feature_flag:write"]
}'
Step 3: Rotate Personal API Keys
set -euo pipefail
# 1. Create new key in PostHog Settings > Personal API Keys
# 2. Update secret in your deployment platform
# Vercel:
vercel env rm POSTHOG_PERSONAL_API_KEY production
vercel env add POSTHOG_PERSONAL_API_KEY production
# GitHub Actions:
gh secret set POSTHOG_PERSONAL_API_KEY --body "phx_new_key_here"
# 3. Verify new key works
curl -s "https://app.posthog.com/api/projects/" \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" | jq '.[0].name'
# 4. Delete old key in PostHog dashboard
Step 4: Prevent Key Leaks
# Git pre-commit hook to catch PostHog personal keys
# .git/hooks/pre-commit (or use husky)
#!/bin/bash
if git diff --cached --diff-filter=ACM | grep -qE 'phx_[a-zA-Z0-9]{20,}'; then
echo "ERROR: PostHog personal API key (phx_) detected in staged files!"
echo "Remove it and use environment variables instead."
exit 1
fi
# .github/secret-scanning.yml (or use GitHub's built-in secret scanning)
patterns:
- name: PostHog Personal API Key
regex: 'phx_[a-zA-Z0-9]{20,}'
severity: critical
Step 5: Server-Side Key Isolation
// lib/posthog-server.ts — Personal key never leaves the server
import { PostHog } from 'posthog-node';
const posthog = new PostHog(process.env.NEXT_PUBLIC_POSTHOG_KEY!, {
host: 'https://us.i.posthog.com',
// personalApiKey ONLY used server-side for local flag evaluation
personalApiKey: process.env.POSTHOG_PERSONAL_API_KEY,
});
// API routes that proxy admin operations
// Never expose the personal key to the client
export async function getFeatureFlagsForUser(userId: string) {
return posthog.getAllFlags(userId);
}
