Provisioning API

PostHog's provisioning API lets you create PostHog accounts for your users and deep link them into their PostHog project.

It's intended for partners and platform integrations. If you're integrating your own app with your own PostHog account, you probably want OAuth or a personal API key instead.

Jump to the full Node.js example to see the complete flow in code.

How it works

The flow uses OAuth 2.0 with PKCE (Proof Key for Code Exchange), so there are no shared secrets to manage. Your application is identified by a metadata document hosted on your domain.

Onboarding (once per user)

1. POST /account_requests  →  authorization code
2. POST /oauth/token        →  access + refresh tokens
3. POST /resources          →  project token + host

Deep linking (per click, after onboarding)

Reuses the access token from onboarding to mint a single-use URL that logs the user into their PostHog project.

4. POST /deep_links  →  single-use URL (10 min TTL)

Set up as a partner

Host a CIMD metadata document

PostHog uses Client ID Metadata Documents (CIMD) for partner registration. There's no signup form to fill out – you host a JSON document at an HTTPS URL on your domain, and that URL becomes your client_id.

Create a JSON file at a stable HTTPS URL, for example https://yourapp.com/.well-known/posthog-client.json:

{
  "client_id": "https://yourapp.com/.well-known/posthog-client.json",
  "client_name": "Your App Name",
  "redirect_uris": ["https://yourapp.com/callbacks/posthog"],
  "logo_uri": "https://yourapp.com/logo.png",
  "token_endpoint_auth_method": "none",
  "grant_types": ["authorization_code"],
  "response_types": ["code"]
}

Requirements:

• client_id must exactly match the URL where this document is hosted.
• redirect_uris is required and must contain at least one HTTPS URI. This is where PostHog redirects existing users during the consent flow.
• logo_uri (optional) must be HTTPS if provided.
• token_endpoint_auth_method must be "none" (CIMD clients are public clients, no client secret).
• The document must be served with Content-Type: application/json and be under 5 KB.
• The URL must use HTTPS, include a path component, and must not contain query parameters or fragments.

PostHog fetches and caches this document automatically. Subsequent requests reuse the cached version and refresh it in the background based on your Cache-Control: max-age header (clamped between 5 minutes and 24 hours, default 1 hour).

Once your metadata document is live, you can start calling the API. The first request auto-registers your app and returns HTTP 202; retry after a few seconds.

Link your partner app to a PostHog organization (optional)

By default, a CIMD partner app is unverified and capped at 10 account requests per hour. You can link the app to a PostHog organization with a verification token to raise that to 100/hour and surface the partner integration to that org's admins.

1. In PostHog, go to Organization settings → CIMD verification tokens and click Create token. Copy the phvt_… value – it's only shown once.

2. Add a posthog_verification_token field to your CIMD metadata document:

   JSON

   PostHog AI

   {
     "client_id": "https://yourapp.com/.well-known/posthog-client.json",
     "client_name": "Your App Name",
     "redirect_uris": ["https://yourapp.com/callbacks/posthog"],
     "logo_uri": "https://yourapp.com/logo.png",
     "token_endpoint_auth_method": "none",
     "grant_types": ["authorization_code"],
     "response_types": ["code"],
     "posthog_verification_token": "phvt_..."
   }

3. The next time PostHog refreshes the metadata document, the app is linked to the matching organization and the rate limit is bumped.

The token is only used to prove ownership of the partner app – it isn't sent on API requests. You can rotate or revoke a token at any time from the same settings page. Revocation clears the link on the next metadata refresh, so a leaked or stale token can't keep an app linked to your org.

API reference

All endpoints are on https://us.posthog.com (US region) or https://eu.posthog.com (EU region).

Every request must include the API-Version: 0.1d header.

Step 1: Create an account

Create a PostHog account for a user by email. If the user is new, PostHog creates the account and returns an authorization code immediately. If the user already exists, the response tells you to redirect them for consent.

Generate a PKCE code verifier and challenge before making this request:

# Generate PKCE values
CODE_VERIFIER=$(openssl rand -base64 32 | tr -d '=' | tr '+/' '-_')
CODE_CHALLENGE=$(echo -n "$CODE_VERIFIER" | openssl dgst -sha256 -binary | openssl base64 | tr -d '=' | tr '+/' '-_')

BODY=$(cat <<JSON
{
  "id": "req_unique_request_id",
  "email": "user@example.com",
  "name": "Jane Doe",
  "client_id": "https://yourapp.com/.well-known/posthog-client.json",
  "code_challenge": "$CODE_CHALLENGE",
  "code_challenge_method": "S256",
  "configuration": {
    "region": "US",
    "organization_name": "Acme Corp"
  }
}
JSON
)

curl -X POST https://us.posthog.com/api/agentic/provisioning/account_requests \
  -H "Content-Type: application/json" \
  -H "API-Version: 0.1d" \
  -d "$BODY"

Request fields:

New user response (HTTP 200):

{
  "id": "req_unique_request_id",
  "type": "oauth",
  "oauth": {
    "code": "abc123...authorization_code"
  }
}

The user receives a welcome email with a link to set their password and access their dashboard.

Existing user response (HTTP 200):

{
  "id": "req_unique_request_id",
  "type": "requires_auth",
  "requires_auth": {
    "url": "https://us.posthog.com/api/agentic/authorize?state=xyz..."
  }
}

When type is requires_auth, redirect the user to the provided URL. After they approve, PostHog redirects them to your redirect_uris with a code query parameter that you use in step 2.

Step 2: Exchange the code for tokens

Exchange the authorization code for an access token and refresh token. The token endpoint uses standard application/x-www-form-urlencoded encoding.

curl -X POST https://us.posthog.com/api/agentic/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "API-Version: 0.1d" \
  -d "grant_type=authorization_code&code=abc123...authorization_code&code_verifier=$CODE_VERIFIER"

Request fields:

Response (HTTP 200):

{
  "token_type": "bearer",
  "access_token": "phx_abc123...",
  "refresh_token": "phr_def456...",
  "expires_in": 3600,
  "account": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "payment_credentials": "orchestrator",
    "available_teams": [
      {
        "id": 12345,
        "name": "Default project",
        "organization_id": "01234567-89ab-cdef-0123-456789abcdef",
        "organization_name": "Acme Corp"
      }
    ]
  }
}

Authorization codes expire after 5 minutes and can only be used once. Access tokens expire after 1 hour. Use the refresh token to get new tokens.

Token endpoint errors use the standard OAuth 2.0 format:

{
  "error": "invalid_grant",
  "error_description": "Invalid or expired authorization code"
}

Step 3: Provision a project

Use the access token to provision a PostHog project and get credentials.

curl -X POST https://us.posthog.com/api/agentic/provisioning/resources \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer phx_abc123..." \
  -H "API-Version: 0.1d" \
  -d '{
    "service_id": "analytics",
    "label_prefix": "Acme Co",
    "configuration": {
      "project_name": "My App - Production"
    }
  }'

Request fields:

Response (HTTP 200):

{
  "status": "complete",
  "id": "12345",
  "service_id": "analytics",
  "complete": {
    "access_configuration": {
      "api_key": "phc_abc123...",
      "host": "https://us.posthog.com",
      "personal_api_key": "phx_def456..."
    }
  }
}

Response fields:

Deep linking

For recurring deep links from your application into PostHog – the most common case is an "Open in PostHog" button on a user's connected project – use the deep-link endpoint. Each call returns a short-lived, single-use URL that logs the user into their PostHog project on click. There's no consent screen and no email-mismatch friction: the URL mints a fresh PostHog session for the right user, overriding any other session the browser happens to have.

curl -X POST https://us.posthog.com/api/agentic/provisioning/deep_links \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer phx_abc123..." \
  -H "API-Version: 0.1d" \
  -d '{
    "purpose": "dashboard"
  }'

Authenticate with the access_token you got from Step 2 – the same Bearer credential you use for /resources. The token is scoped to a single team, so the resulting deep link lands the user in the correct project.

Request fields:

Response:

{
  "purpose": "dashboard",
  "url": "https://us.posthog.com/agentic/login?token=...&team_id=12345",
  "expires_at": "2026-05-20T21:00:00Z"
}

The returned url is valid for 10 minutes and can only be opened once, so don't pre-render it as the button's href. Wire the button click to your backend, call /deep_links there, then redirect the user to the returned URL.

Requires a trusted partner record

This endpoint is gated on the provisioning_can_issue_deep_links flag on your partner record, which is only enabled for partners admin-onboarded by PostHog. If you get a deep_links_not_enabled 403, ask PostHog to enable it for your CIMD app.

Rotate project credentials

Rotate the project token and create a new personal API key for an existing provisioned project:

curl -X POST https://us.posthog.com/api/agentic/provisioning/resources/12345/rotate_credentials \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer phx_abc123..." \
  -H "API-Version: 0.1d" \
  -d '{
    "label_prefix": "Acme Co"
  }'

Request fields:

The response has the same shape as the project provisioning response and includes the rotated api_key, host, and new personal_api_key.

Refresh tokens

Access tokens expire after 1 hour. Use the refresh token to get new credentials:

curl -X POST https://us.posthog.com/api/agentic/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "API-Version: 0.1d" \
  -d "grant_type=refresh_token&refresh_token=phr_def456..."

Response (HTTP 200):

{
  "token_type": "bearer",
  "access_token": "phx_new_token...",
  "refresh_token": "phr_new_refresh...",
  "expires_in": 3600
}

Each refresh token is single-use. The response includes a new refresh token for subsequent refreshes.

Available scopes

The scopes field in the account request controls what permissions the access token receives. If omitted, a default set of scopes is granted. Available scopes:

What the user gets

When you provision a new account, the user receives:

• A welcome email with a link to set their password.
• Full dashboard access at us.posthog.com (or eu.posthog.com for EU).
• The PostHog free tier across all products – no credit card required.

Your integration gets back the project token and host, so you can start sending events the moment the API call returns.

Error handling

Provisioning endpoints (account_requests, resources) return errors in this format:

{
  "type": "error",
  "error": {
    "code": "error_code",
    "message": "Human-readable description"
  }
}

The token endpoint uses the standard OAuth 2.0 error format instead:

{
  "error": "error_code",
  "error_description": "Human-readable description"
}

Common error codes:

Rate limits

All provisioning endpoints are rate limited.

CIMD registration (first request from a new client_id):

• 5 requests per minute per IP (burst)
• 10 requests per hour per IP (sustained)
• 100 new client registrations per hour globally
• 5 new client registrations per domain per hour

Account requests (per partner, per hour):

• 10/hour for unverified CIMD partners
• 100/hour for partners linked to a PostHog organization via a verification token

Email team-growth@posthog.com if you need a higher limit for production use.

Full example

Here's a complete example in Node.js:

import crypto from 'node:crypto';

const CLIENT_ID = 'https://yourapp.com/.well-known/posthog-client.json';
const BASE_URL = 'https://us.posthog.com';

async function provisionPostHogAccount(email, name) {
  // Generate PKCE values
  const codeVerifier = crypto.randomBytes(32).toString('base64url');
  const codeChallenge = crypto
    .createHash('sha256')
    .update(codeVerifier)
    .digest('base64url');

  // Step 1: Create account
  const accountRes = await fetch(
    `${BASE_URL}/api/agentic/provisioning/account_requests`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'API-Version': '0.1d',
      },
      body: JSON.stringify({
        id: crypto.randomUUID(),
        email,
        name,
        client_id: CLIENT_ID,
        code_challenge: codeChallenge,
        code_challenge_method: 'S256',
        configuration: { region: 'US' },
      }),
    }
  );

  if (!accountRes.ok) {
    const err = await accountRes.json();
    throw new Error(
      `Account request failed (${accountRes.status}): ${err.error?.message || JSON.stringify(err)}`
    );
  }

  const account = await accountRes.json();

  if (account.type === 'requires_auth') {
    // Existing user - redirect them to account.requires_auth.url
    return { type: 'requires_auth', url: account.requires_auth.url };
  }

  if (account.type !== 'oauth') {
    throw new Error(account.error?.message || 'Unexpected response type');
  }

  // Step 2: Exchange code for tokens
  const tokenRes = await fetch(`${BASE_URL}/api/agentic/oauth/token`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      'API-Version': '0.1d',
    },
    body: new URLSearchParams({
      grant_type: 'authorization_code',
      code: account.oauth.code,
      code_verifier: codeVerifier,
    }),
  });

  if (!tokenRes.ok) {
    const err = await tokenRes.json();
    throw new Error(
      `Token exchange failed (${tokenRes.status}): ${err.error_description || JSON.stringify(err)}`
    );
  }

  const tokens = await tokenRes.json();

  // Step 3: Provision a project
  const resourceRes = await fetch(
    `${BASE_URL}/api/agentic/provisioning/resources`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer ${tokens.access_token}`,
        'API-Version': '0.1d',
      },
      body: JSON.stringify({
        service_id: 'analytics',
        label_prefix: 'Acme Co',
        configuration: { project_name: 'Production' },
      }),
    }
  );

  if (!resourceRes.ok) {
    const err = await resourceRes.json();
    throw new Error(
      `Resource provisioning failed (${resourceRes.status}): ${err.error?.message || JSON.stringify(err)}`
    );
  }

  const resource = await resourceRes.json();

  return {
    type: 'provisioned',
    apiKey: resource.complete.access_configuration.api_key,
    host: resource.complete.access_configuration.host,
    personalApiKey: resource.complete.access_configuration.personal_api_key,
    projectId: resource.id,
    accessToken: tokens.access_token,
    refreshToken: tokens.refresh_token,
  };
}

For the "Open in PostHog" button, call this from your click handler with the user's stored access_token, then redirect the browser to the returned URL:

async function getDeepLinkUrl(accessToken) {
  const res = await fetch(
    `${BASE_URL}/api/agentic/provisioning/deep_links`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer ${accessToken}`,
        'API-Version': '0.1d',
      },
      body: JSON.stringify({ purpose: 'dashboard' }),
    }
  );

  if (!res.ok) {
    const err = await res.json();
    throw new Error(
      `Deep link request failed (${res.status}): ${err.error?.message || JSON.stringify(err)}`
    );
  }

  const { url } = await res.json();
  return url;
}