Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 34 additions & 4 deletions contents/docs/integrate/provisioning.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@ Most of the provisioning API is self-serve. The rest needs PostHog to turn it on

| Capability | How to get it |
| ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Create accounts and organizations for your users | Self-serve. [Register your app](#register-your-app) and [sign your requests](#sign-requests-with-a-key). |
| Create accounts and organizations for your users | Self-serve. [Register your app](#register-your-app), pass the [review](#how-posthog-reviews-your-app), and [sign your requests](#sign-requests-with-a-key). |
| Provision projects and [rotate their credentials](#rotate-project-credentials) | Self-serve, once you register. |
| Higher [rate limits](#rate-limits) | Self-serve. Signing your requests gives you 5x the base limits, and [linking your app to an organization](#link-your-partner-app-to-a-posthog-organization-optional) doubles that. |
| [Deep links](#deep-linking) that log users into their project | Ask PostHog. Your app must also sign its requests. |
Expand Down Expand Up @@ -93,6 +93,7 @@ Create a JSON file at a stable HTTPS URL, for example `https://yourapp.com/.well
{
"client_id": "https://yourapp.com/.well-known/yourapp.json",
"client_name": "Your App Name",
"client_uri": "https://yourapp.com",
"redirect_uris": ["https://yourapp.com/callbacks/posthog"],
"logo_uri": "https://yourapp.com/logo.png",
"token_endpoint_auth_method": "private_key_jwt",
Expand All @@ -112,16 +113,16 @@ Requirements:
- **`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 `"private_key_jwt"` with an HTTPS `jwks_uri` if your app creates accounts. Your app then authenticates by signing an assertion with your own key, which also raises your [rate limits](#rate-limits). Publish your keys at the `jwks_uri` before you register. See [sign requests with a key](#sign-requests-with-a-key).
- The document must be served with `Content-Type: application/json` and be under 5 KB.
- The document must be served with `Content-Type: application/json` and be under 5 KB. A `charset` parameter is fine. PostHog refuses a document that declares `com.posthog.provisioning` and is served with another type, such as `text/plain` or `text/html`.
- The URL must use HTTPS, include a path component, and must not contain query parameters or fragments.
- The URL must be on a domain you control. PostHog doesn't accept metadata documents on throwaway hosts.
- The URL must be on a domain you control. PostHog doesn't accept metadata documents on throwaway hosts. See [how PostHog reviews your app](#how-posthog-reviews-your-app) for where to host it.

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).

### Register your app

Once your metadata document is live, register it. PostHog fetches the document, validates it, and turns on provisioning access if it declares `com.posthog.provisioning`.
Once your metadata document is live, register it. PostHog fetches the document, validates it, and turns on provisioning access if it declares `com.posthog.provisioning` and your app passes [review](#how-posthog-reviews-your-app).

This call is not authenticated, because an app that hasn't registered yet has no credential to present. That's why the opt-in lives in your document rather than in this request.

Expand Down Expand Up @@ -168,6 +169,35 @@ You can also verify a [signed assertion](#sign-requests-with-a-key) end to end b

Until your app is registered, the other endpoints return HTTP 401 with a message pointing back here.

#### How PostHog reviews your app

After you register a client that declares `com.posthog.provisioning`, PostHog reviews it before it can provision. Until the review accepts your app, provisioning stays inactive: your app can't create accounts or provision resources. Most reviews finish within minutes. Some go to PostHog staff and take longer.

To check the status, call the [registration endpoint](#register-your-app) again. While your app is under review or blocked, registration fails, and its `provisioning_enabled` check fails with one of these details:

| Detail | What it means |
| ----------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `PostHog is reviewing this client before it can provision. Register again in a few minutes to check.` | The review is in progress. Call the registration endpoint again in a few minutes. |
| `PostHog staff are reviewing this client before it can provision. Register again later to check.` | PostHog staff are reviewing your app. Call the registration endpoint again later. |
| `Provisioning is blocked for this client. Contact PostHog support if that is unexpected.` | PostHog blocked provisioning for your app, because the review rejected it or staff blocked it later. Registering again doesn't lift the block. |

Once the review accepts your app, the `provisioning_enabled` check reports `Active`.

PostHog staff can change the decision later. They can block an accepted app, for example after reports of abuse, and they can accept an app that was blocked. If your app is blocked and you think that is a mistake, contact PostHog support. When staff lift a block, call the registration endpoint again to check, and have your users connect again: blocking signs out every connection your app had.

The review reads your metadata document and researches your app on the web. PostHog loads the homepage at your `client_uri` and searches the web for your product, your domain, and reports of abuse. A model then judges three things from that evidence: whether your app is a real product of the organization that owns the domain, whether it shows signs of abuse, and whether the metadata document is on your own site. When the model isn't sure, PostHog staff decide.

To pass:

- Host the metadata document on the live production domain of your product. A subdomain such as `api.yourapp.com` is fine.
- Use a real `client_name` that matches your product.
- Set `client_uri` to your product's homepage.
- Optionally, add `logo_uri`, `tos_uri`, `policy_uri`, and `contacts` on the same domain. These help the review.

PostHog doesn't accept a `client_id` on `localhost`, on a private or reserved IP address, or on a throwaway host such as a tunnel (for example ngrok), a request bin, or a JSON or paste hosting service. The review also won't accept a document on a site where anyone can publish content, such as a public Etherpad, a public git forge, or shared object storage. Register from the website your users actually use, not from a local or preview environment.

While a client that PostHog accepted stays active, another client whose metadata document is on the same host is accepted even when the model isn't sure about it, as long as the document is on your own site and shows no signs of abuse. For example, after `https://api.yourapp.com/.well-known/yourapp.json` is accepted, `https://api.yourapp.com/.well-known/yourapp-staging.json` is accepted too. A client on another host, such as `staging.yourapp.com`, gets its own review.

<a id="sign-requests-with-a-key-optional" />

### Sign requests with a key
Expand Down
Loading