:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Vercel SSO + ngrok Local Development Setup
This guide documents the complete setup process for testing Vercel SSO integration locally using ngrok for HTTPS.
Prerequisites
- ngrok installed and authenticated:
brew install --cask ngrok - 1Password CLI installed (if using 1Password option):
brew install --cask 1password-cli
Step 1: Configure ngrok Tunnels
Follow the PostHog ngrok setup guide to configure ngrok.
Quick version:
- Find your ngrok config location:
ngrok config check --log=stdout - Edit the config file to add tunnels for Django (port 8000) and webpack (port 8234)
- Start only the Django tunnel:
ngrok start django
This will give you an HTTPS URL for port 8000, e.g., https://abc123.ngrok-free.dev
Note: You only need the Django tunnel. Vite will serve assets locally on port 8234, and the Django tunnel will proxy requests to it.
Step 2: Configure PostHog Environment Variables
Create a .env.vercel file in the PostHog root directory with your ngrok URL (copy from .env.vercel.example in this directory)
# Enable HTTPS mode for local development
LOCAL_HTTPS=1
DEBUG=1
# ngrok tunnel URL for HTTPS local development (update with your ngrok URL)
SITE_URL=https://your-ngrok-tunnel.ngrok-free.dev
# Keep Vite on localhost: the browser loads dev assets from it directly, not through the tunnel
JS_URL=http://localhost:8234
WEBPACK_HOT_RELOAD_HOST=0.0.0.0
# Trust ngrok's X-Forwarded-Proto so Django treats tunneled requests as HTTPS
IS_BEHIND_PROXY=1
TRUST_ALL_PROXIES=1
# Vercel integration credentials (automatically loaded from 1Password)
VERCEL_CLIENT_INTEGRATION_ID="op://General/Vercel Client Integration Secret/client id"
VERCEL_CLIENT_INTEGRATION_SECRET="op://General/Vercel Client Integration Secret/client secret"
# URL slug of your Vercel integration, from vercel.com/integrations/<slug> (defaults to the production slug "posthog")
VERCEL_INTEGRATION_SLUG=your-integration-slug
Notes:
- The first time the tunneled page loads, Chrome asks to let the site access apps on this device. Allow it, or the page stays blank because the Vite requests to
localhost:8234never start. - Start the stack inside flox so
pnpmis on the path:flox activate -- op run --env-file=.env.vercel -- hogli up -d. The stack starts its own ngrok tunnel, so don't run a second one.
Step 3: Configure Vercel Integration Settings
In your Vercel integration settings:
Configuration URL: Set to your Django tunnel URL (port 8000)
- Example:
https://abc123.ngrok-free.dev
- Example:
Redirect URL: Set to
{your_ngrok_url}/connect/vercel/callback- This enables the "Link Existing Account" connectable account flow
- Example:
https://abc123.ngrok-free.dev/connect/vercel/callback
Step 4: Start Development Servers
Run PostHog with 1Password to load the Vercel credentials:
op run --env-file=.env.vercel -- bin/start
This will:
- Read your
.env.vercelfile - Fetch the Vercel credentials from 1Password
- Start both Django and Vite dev servers with all environment variables loaded
Architecture Notes
Installation vs SSO Flows
Vercel marketplace integrations have two separate flows:
Installation Flow (API-based):
- Endpoint:
/api/vercel/v1/installations/{id} - Triggered by API calls from Vercel to PostHog
- No user-facing web page
- Creates the integration record in PostHog
- Endpoint:
SSO Flow (web-based):
- Endpoint:
/login/vercel/ - Triggered when user clicks "Connect Account" in Vercel
- Authenticates the user and links their PostHog account
- Returns user back to Vercel using the
urlparameter
- Endpoint:
Connectable Account Flow (Link Existing Account)
When a user clicks "Link Existing Account" in the Vercel Marketplace:
- Vercel opens a popup to our Redirect URL (
/connect/vercel/callback) with an OAuth code - The Marketplace request has no
state. PostHog exchanges the Marketplace code for an access token viaPOST /v2/oauth/access_tokenand keeps that grant, encrypted, in the cache for 10 minutes. The resource import must use this grant, because Vercel waits for the import on the Marketplace installation - PostHog sends the popup to Vercel's external install page (
https://vercel.com/integrations/{VERCEL_INTEGRATION_SLUG}/new) with a randomstate, and stores the same value in a host-only__Host-cookie. PostHog keeps the Marketplace'snextlink for the return, and a browser holds at most a few pendingstatecookies - Vercel returns to the Redirect URL with
source=external, a new code, and the samestate. PostHog rejects the request when the browser has no matching cookie, or when the request has nostate. PostHog exchanges the new code only to confirm that it belongs to the same Vercel user as the Marketplace code, and the link session carries the Marketplace grant - If the user isn't logged in, they're redirected to
/loginfirst - The user selects which PostHog organization to link
- An
OrganizationIntegrationrecord is created withtype=connectable - The popup closes and returns the user to Vercel
Billing stays with PostHog for connected accounts - no billing provider migration is needed.
Troubleshooting
"This host is not allowed" from Vite
Solution: Add ngrok domains to allowedHosts in vite.config.ts (see Step 3)
CORS errors when loading JavaScript assets
Solution: Add your ngrok domain to the cors.origin array in vite.config.ts (see Step 3)
JWT validation failing with "Audience doesn't match"
Solution: Verify VERCEL_CLIENT_INTEGRATION_ID matches your Vercel integration's Client ID exactly
Getting 400/404 errors during installation
Solution:
- Verify Configuration URL points to your Django ngrok tunnel (port 8000)
- Verify Redirect URL is set to
{ngrok_url}/connect/vercel/callback - Check Django logs for detailed error messages
Blank page (React not mounting) after switching branches
Vite caches resolved module paths in node_modules/.pnpm.
When you switch branches, pnpm store hashes can change, leaving Vite with stale references (typically @react-refresh returns 500).
Solution: Restart the Vite dev server.
You can verify by checking curl -s -o /dev/null -w "%{http_code}" http://localhost:8234/@react-refresh — it should return 200.
Environment variables not loaded
Solution:
- Verify you're authenticated with 1Password CLI:
op whoami - Test credential loading:
op run --env-file=.env.vercel -- printenv | grep VERCEL - Restart your Django server
- Verify ngrok URL is set: Check that
JS_URLandNGROK_ORIGINin your.env.vercelmatch your ngrok tunnel URL
JS_URL doesn't affect Vite dev scripts
In development, the Vite dev server script tags (@vite/client, @react-refresh, src/index.tsx) are emitted by get_js_url() in posthog/utils.py.
When the page is served over HTTPS (e.g. via ngrok), the URL stays as http://localhost:8234 so the browser can load Vite assets directly — browsers exempt localhost from mixed-content blocking.
For HTTP requests where JS_URL=http://localhost:8234, the host is rewritten to the request origin so non-localhost dev environments (Docker containers, sandboxes) can still reach Vite.
JS_URL only sets window.JS_URL for the production bundle loader.
1Password shows "<concealed by 1Password>" in logs
This is normal! 1Password CLI conceals sensitive values in stdout for security. The actual values are correctly passed to your application as environment variables.
Testing the Integration
Automated Tests
Run the Vercel integration test suite:
pytest ee/vercel/test/test_integration.py -v
The test suite includes:
- Unit tests: Individual function testing
- Regression tests: Tests for specific bugs that were fixed (see
TestVercelInstallationRegressions) - E2E tests: Complete installation flow simulations (see
TestVercelInstallationE2E)
Manual Testing Checklist
Before releasing changes to the Vercel integration, manually verify the following scenarios:
Scenario 1: Brand New User Installation
Setup: Use an email that doesn't exist in PostHog
- Start ngrok, Django, and Vite as described above
- In Vercel, navigate to your integration and click "Install"
- Complete the installation flow
Expected:
- Installation completes without errors
- New organization is created in PostHog
- New user is created with the email from Vercel
- User is added as Owner of the organization
- Click "Connect Account" → SSO works immediately (no login required)
Scenario 2: Existing PostHog User (No Prior Vercel)
Setup: Create a PostHog account manually with an email, then use that email in Vercel
- Create a user in PostHog:
User.objects.create_user(email="[email protected]", password="test") - In Vercel, install with the same email
Expected:
- Installation completes without errors
- New organization is created
- Existing user is added as Owner of the new organization
- Click "Connect Account" → SSO logs in the existing account when Vercel's signed token has a verified, matching email
- Accounts with 2FA or enforced SSO, or without a verified matching email, still require PostHog login
Scenario 3: Trusted Vercel User (Second Installation)
Setup: User who already has one Vercel installation
- Complete Scenario 1 first
- Install a second Vercel integration with the same email
Expected:
- Installation completes without errors
- Second organization is created
- Same user is added as Owner of the second organization
- Click "Connect Account" → SSO works immediately with a verified, matching email and no additional account login requirements
Scenario 4: Inactive User Reactivation
Setup: Create an inactive user, then install with that email
- Create inactive user:
User.objects.create_user(email="[email protected]", password="test", is_active=False) - Install Vercel integration with that email
Expected:
- Installation completes without errors
- User is reactivated (is_active=True)
- User is added to the new organization
Scenario 5: Link Existing Account (Connectable Account)
Setup: Have an existing PostHog account with admin access to an organization
- In the Vercel Marketplace, click "Add" on the PostHog integration
- Choose "Link Existing Account"
- A popup opens — log in with your PostHog credentials
- Select an organization from the dropdown
- Click "Connect organization"
Expected:
- Popup passes through Vercel's install page once, then returns to
/connect/vercel/callbackwith astateparameter - Popup opens to PostHog login page (if not already logged in)
- After login, org selector is shown with orgs where user is admin/owner
- Already-linked orgs are not available for selection
- Clicking "Connect organization" shows success message
- "Return to Vercel" button redirects back to Vercel
-
OrganizationIntegrationrecord created withconfig.type = "connectable"
Quick Local Verification
To quickly verify the fix for existing users without Vercel mappings:
# In Django shell: python manage.py shell
from posthog.models.user import User
from posthog.models.organization_integration import OrganizationIntegration
# Create test user without any Vercel mappings
User.objects.create_user(email="[email protected]", password="test", first_name="Test")
# Verify no Vercel mappings exist
for oi in OrganizationIntegration.objects.filter(kind="vercel"):
mappings = oi.config.get("user_mappings", {})
user_ids = list(mappings.values())
user = User.objects.filter(email="[email protected]").first()
assert user.pk not in user_ids, "User should have no mappings"
# Now install via Vercel with [email protected]
# User should be added to org without errors
Basic Manual Testing
- Start ngrok, Django, and Vite as described above
- In Vercel, navigate to your integration and click "Install"
- Follow the installation flow
- Click "Connect Account" to test SSO
- You should be redirected to PostHog, authenticate, and return to Vercel
Clean Up
When you're done testing:
# Stop ngrok
# Press Ctrl+C in the ngrok terminal
# Stop Django and Vite servers
# Press Ctrl+C in each terminal
# (Optional) Unset environment variables
direnv deny