> For the complete documentation index, see [llms.txt](https://docs.appmixer.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.appmixer.com/connector-configuration/posthog.md).

# PostHog

The Appmixer PostHog connector uses **Personal API Key** authentication. No OAuth app registration is required — you only need to generate a Personal API key in your PostHog account and know your PostHog instance URL.

***

## 1. Identify Your PostHog Host URL

PostHog can be used in the cloud or self-hosted. Use the appropriate base URL:

| Instance        | Host URL                                                       |
| --------------- | -------------------------------------------------------------- |
| **US Cloud**    | `https://us.posthog.com`                                       |
| **EU Cloud**    | `https://eu.posthog.com`                                       |
| **Self-hosted** | Your own instance URL (e.g. `https://posthog.yourcompany.com`) |

***

## 2. Generate a Personal API Key

1. Log in to your PostHog instance.
2. Click your avatar or name in the top-right corner and go to **Settings**.
3. In the left sidebar, navigate to **User → Personal API Keys**.
4. Click **+ Create personal API key**.
5. Enter a descriptive **Label** (e.g. `Appmixer Integration`).
6. Under **Organization & project access**, choose **All access**, or limit the key to the **Organizations** or **Projects** you want to use in Appmixer. The **List Projects** component and the project pickers only show projects the key can access.
7. Under **Scopes**, either pick the **All access** preset or grant the scopes listed in [Required scopes](#required-scopes) below.
8. Click **Create key**.
9. Copy the generated key immediately — it will not be shown again.

{% hint style="warning" %}
The Personal API key is shown **only once** at creation. Store it securely before closing the dialog.
{% endhint %}

{% hint style="info" %}
Personal API keys authenticate as you (the user who created them) and inherit your PostHog permissions. For production integrations, consider creating a dedicated PostHog user with appropriate project access.
{% endhint %}

### Required scopes

PostHog Personal API keys are scoped — a request outside the key's scopes is rejected with `403`. Grant the scopes for the components you plan to use:

| Scope               | Needed for                                                                                            |
| ------------------- | ----------------------------------------------------------------------------------------------------- |
| `user:read`         | Connecting the account (Appmixer verifies the key with `GET /api/users/@me/`) — **always required**   |
| `project:read`      | List Projects, the project pickers, Capture Event and Identify User (they read the project's API key) |
| `person:read`       | Get Person, Find Persons                                                                              |
| `person:write`      | Delete Person                                                                                         |
| `annotation:read`   | New Annotation trigger                                                                                |
| `annotation:write`  | Create Annotation                                                                                     |
| `cohort:read`       | List Cohorts                                                                                          |
| `feature_flag:read` | List Feature Flags                                                                                    |
| `query:read`        | Run Query                                                                                             |

The **Make API Call** component needs whichever scope the called endpoint requires. The **New Action Event** trigger needs no scope — PostHog pushes the events to its webhook URL.

***

## 3. Connect in Appmixer

When adding a PostHog component in Appmixer, you will be prompted to authenticate. Provide:

| Field                | Value                                                  |
| -------------------- | ------------------------------------------------------ |
| **PostHog Host**     | Your PostHog base URL (from Step 1, no trailing slash) |
| **Personal API Key** | The key generated in Step 2                            |

Appmixer will verify the credentials by calling `GET /api/users/@me/` on your PostHog instance. Your account email will be used as the display name for the connection.

***

## Troubleshooting

### "Authentication failed" / 401 Unauthorized

* Make sure the **Personal API Key** is correct and has not been revoked.
* Regenerate the key under **Settings → User → Personal API Keys** if needed.

### "Connection refused" / network error

* Double-check the **PostHog Host** URL. It should include the protocol (`https://`) and no trailing slash.
* For self-hosted instances, confirm the URL is publicly reachable from the Appmixer server.

### 403 Forbidden

* `API key missing required scope '…'` — add the named scope to the key. Connecting the account fails this way when `user:read` is missing.
* Compare the key's scopes with [Required scopes](#required-scopes). Scopes of an existing key can be edited under **Settings → User → Personal API Keys**.
* The key may not have access to the project — check its **Organization & project access**.
* Your PostHog user may lack permissions for the requested project or resource.

***

## Resources

* [PostHog Personal API Keys documentation](https://posthog.com/docs/api#authentication)
* [PostHog API reference](https://posthog.com/docs/api)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.appmixer.com/connector-configuration/posthog.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.