Skip to content

docs(provisioning): require signing and add a partner capability table - #21242

Merged
MattBro merged 5 commits into
masterfrom
matt/provisioning-signing-required
Oct 19, 2026
Merged

MattBro merged 5 commits into
masterfrom
matt/provisioning-signing-required

Conversation

@MattBro

@MattBro MattBro commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

Changes

  • Partner apps that create accounts must sign provisioning requests with private_key_jwt. The "Sign requests with a key" section now says so, and the old #sign-requests-with-a-key-optional anchor still works.
  • The page states only the lasting rule: an app that creates accounts must sign, and unsigned account requests and token calls get a 401. The page does not document the grace period for apps registered before October 16, 2026, because that period ends on October 23, 2026.
  • The Node.js examples read the private key from JWKS_PRIVATE_SIGNING_KEY, because the key belongs to the partner and is not specific to PostHog.
  • The registration, account request, and token examples now include client_assertion.
  • The switch order is spelled out: publish keys, call registration in each region, then start signing.
  • A short note says that users of an unverified app are asked on first login whether to keep it connected.
  • A new "What your app can do" section lists each partner capability. For each one, it says if the capability is self-serve or if PostHog must turn it on, and how to ask.
  • The CIMD and JWKS examples use generic names (yourapp.json, jwks.json). A partner's metadata document describes its own client, so the examples do not suggest a PostHog-specific one.
  • The project provisioning section says that a personal_api_key is off by default. Before, it said that the response never includes one.
  • Support links no longer tell partners to choose the Authentication topic, because the in-app support form has no topic picker.

Ship this after the PostHog changes that enforce signing (PostHog/posthog#112182) and ask users about unverified apps on first login (PostHog/posthog#117756).

Checks

Checklist

  • I've read the docs and/or content style guides.
  • Words are spelled using American English
  • Use relative URLs for internal links
  • I've checked the pages added or changed in the Vercel preview build
  • If I moved a page, I added a redirect in vercel.json

🤖 Generated with Claude Code

…accounts

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@MattBro MattBro self-assigned this Oct 15, 2026
@github-actions github-actions Bot added docs Improvements or additions to product documentation, "Docs" content PR only touches files under contents/ labels Oct 15, 2026
@github-actions

github-actions Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

Deploy preview

Status Details Updated (UTC)
🟢 Ready View preview Oct 16, 2026 09:40PM

Changed pages

Page Source
Provisioning API contents/docs/integrate/provisioning.mdx

@github-actions

github-actions Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

Vale prose linter → found 4 errors, 12 warnings, 15 suggestions in your markdown

Full report → Copy the linter results into an LLM to batch-fix issues.

Linter being weird? Update the rules!

contents/docs/integrate/provisioning.mdx — 4 errors, 12 warnings, 15 suggestions
Line Severity Message Rule
42:71 warning Capitalize 'Logs' for PostHog's product. Use 'logs' for the general industry concept. PostHogBase.ProductNames
42:76 suggestion Address the reader directly. Use 'you' instead of 'the user'. PostHogDocs.DirectAddress
161:185 warning Capitalize 'Endpoints' for PostHog's product. Use 'endpoints' for the general industry concept. PostHogBase.ProductNames
169:41 warning Capitalize 'Endpoints' for PostHog's product. Use 'endpoints' for the general industry concept. PostHogBase.ProductNames
211:26 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
212:21 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
220:8 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
221:8 error Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. PostHogBase.EnDash
263:88 suggestion Address the reader directly. Use 'you' instead of 'the user'. PostHogDocs.DirectAddress
265:30 warning 'jose' is a possible misspelling. PostHogBase.Spelling
404:166 warning 'org's' is a possible misspelling. PostHogBase.Spelling
434:5 warning 'Declare OAuth scopes for your app (optional)' heading should be in sentence case, and product names should be capitalized. PostHogBase.SentenceCase
440:5 warning Capitalize 'Endpoints' for PostHog's product. Use 'endpoints' for the general industry concept. PostHogBase.ProductNames
446:50 suggestion Address the reader directly. Use 'you' instead of 'the user'. PostHogDocs.DirectAddress
446:145 suggestion Address the reader directly. Use 'you' instead of 'the user'. PostHogDocs.DirectAddress
511:1 suggestion Address the reader directly. Use 'you' instead of 'The user'. PostHogDocs.DirectAddress
525:42 suggestion Address the reader directly. Use 'you' instead of 'the user'. PostHogDocs.DirectAddress
660:228 warning Capitalize 'Logs' for PostHog's product. Use 'logs' for the general industry concept. PostHogBase.ProductNames
660:233 suggestion Address the reader directly. Use 'you' instead of 'the user'. PostHogDocs.DirectAddress
672:224 suggestion Address the reader directly. Use 'you' instead of 'the user'. PostHogDocs.DirectAddress
678:50 suggestion Address the reader directly. Use 'you' instead of 'the user'. PostHogDocs.DirectAddress
693:199 suggestion Address the reader directly. Use 'you' instead of 'the user'. PostHogDocs.DirectAddress
754:34 warning 'grantable' is a possible misspelling. PostHogBase.Spelling
760:327 warning Capitalize 'Endpoints' for PostHog's product. Use 'endpoints' for the general industry concept. PostHogBase.ProductNames
762:9 suggestion Address the reader directly. Use 'you' instead of 'the user'. PostHogDocs.DirectAddress
764:35 suggestion Address the reader directly. Use 'you' instead of 'the user'. PostHogDocs.DirectAddress
767:32 warning Use 'PostHog' instead of 'posthog'. Vale.Terms
772:38 suggestion Address the reader directly. Use 'you' instead of 'the user'. PostHogDocs.DirectAddress
776:14 warning Capitalize 'Endpoints' for PostHog's product. Use 'endpoints' for the general industry concept. PostHogBase.ProductNames
1033:74 suggestion Address the reader directly. Use 'you' instead of 'the user'. PostHogDocs.DirectAddress
1033:177 suggestion Address the reader directly. Use 'you' instead of 'the user'. PostHogDocs.DirectAddress

@posthog posthog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PostHog Review · Standard · reviewed 729d0c7: 1 Should fix.

This is the only automatic review while this pull request is a draft. Comment @posthog review to review new changes sooner. Otherwise, a review of the new changes runs when you mark it ready for review.

Comment on lines +156 to +159
If your app can create accounts, it must sign. The [registration](#register-your-app) response shows this as `"can_create_accounts": true`.

- **Registered before October 16, 2026** - your app can keep sending unsigned requests until October 23, 2026 at 16:00 UTC, in both regions. After that, unsigned account requests and token calls get a 401.
- **Registered on or after October 16, 2026** - your app must sign its account requests and token calls from the first one. Unsigned ones get a 401.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 · Align the signing policy with the backend enforcement

For partners with pays_for_customers=true, the linked backend change rejects unsigned requests immediately, without a registration-date grace period. can_create_accounts=true alone does not require signing. This section gives paying partners a false migration window that leads to 401s; align the scope and dates with enforcement.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not a match for the current backend. In the linked change, provisioning_signing applies the same registration-date grace to paying partners as to partners that create accounts, and can_create_accounts=true alone does require signing. PostHog turns on paying-partner status per partner, so a paying partner that cannot create accounts hears about signing directly rather than from these docs.

@github-actions

github-actions Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

Bundle report

Total JS (gzip)

10.37 MiB (no change)

Eager graph (modules shipped in each entrypoint's initial chunks)

Entrypoint Eager size Budget Modules
✅ app 20.75 MiB (+0.4 KiB / +0.0%) report-only 2121
Largest modules in the app closure
Module Size
./src/data/mcp-tools.json 1363.9 KiB
css ./node_modules/.pnpm/css-loader@5.2.7_webpack@5.101.3/node_modules/css-loader/dist/cjs.js??ruleSet[1].rules[8].oneOf[1].use[1]!./node_modules/.pnpm/postcss-loader@4.3.0_postcss@8.5.6_webpack@5.101.3/node_modules/postcss-loader/dist/cjs.js??ruleSet[1].rules[8].oneOf[1].use[2]!./src/styles/global.css 818.7 KiB
./src/components/Stickers/Stickers.tsx 696.4 KiB
./node_modules/.pnpm/@radix-ui+react-icons@1.3.2_react@18.3.1/node_modules/@radix-ui/react-icons/dist/react-icons.esm.js 481.4 KiB
./node_modules/.pnpm/@posthog+brand@0.13.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/x-ray.mjs 481.2 KiB
./node_modules/.pnpm/@posthog+brand@0.13.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/trenchcoat.mjs 450.8 KiB
./node_modules/.pnpm/rehype-raw@7.0.0/node_modules/rehype-raw/lib/index.js + 29 modules 395.1 KiB
./node_modules/.pnpm/@posthog+brand@0.13.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/im-the-driver.mjs 385.8 KiB
./src/hooks/useCustomers.tsx + 59 modules 380.8 KiB
./node_modules/.pnpm/@posthog+brand@0.13.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/tourist.mjs 364.6 KiB
./node_modules/.pnpm/@posthog+icons@0.36.6_react-dom@18.3.1_react@18.3.1__react@18.3.1/node_modules/@posthog/icons/dist/posthog-icons.es.js 354.8 KiB
./node_modules/.pnpm/react-markdown@8.0.7_@types+react@16.14.66_react@18.3.1/node_modules/react-markdown/lib/react-markdown.js + 88 modules 351.4 KiB
./src/components/ProductComparisonTable/index.tsx + 127 modules 310.3 KiB
./node_modules/.pnpm/framer-motion@14.0.0_react-dom@18.3.1_react@18.3.1__react@18.3.1/node_modules/framer-motion/dist/es/render/components/motion/proxy.mjs + 127 modules 287.8 KiB
./node_modules/.pnpm/@posthog+brand@0.13.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/doll-house.mjs 284.1 KiB

Eager-graph budgets are report-only until a baseline is established. Sizes are gzip of public/**/*.js; eager size is webpack module source bytes for the modules actually shipped in the entrypoint's initial chunks (post-tree-shake).

@MattBro
MattBro marked this pull request as ready for review October 15, 2026 16:21
The table lists what a partner app can do and whether it is self-serve or
needs PostHog to turn it on. The CIMD and JWKS examples now use generic
names, because a partner's metadata document describes its own client, not
a PostHog-specific one.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@MattBro MattBro changed the title docs(provisioning): require signed requests for partners that create accounts docs(provisioning): require signing and add a partner capability table Oct 16, 2026

@rafaeelaudibert rafaeelaudibert left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving, but left some suggestions for this PR or a follow-up


#### Switch back to a public client

An app that creates accounts can be a public client only if it was registered before October 16, 2026, and only until October 23, 2026 at 16:00 UTC. After that, its unsigned account requests and token calls get a 401.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we not add this here? This will get outdated very quickly; let's document it for the future, assuming that everyone needs to sign requests.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

removed, the page only says apps that create accounts must sign now: 9cb36dd


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

If PostHog hasn't verified your app, the user is asked the first time they log in whether to keep your app connected to their account. If they disconnect it, your app loses access to their account. Your flow doesn't change, because the account request still returns the authorization code right away. A [verification token](#link-your-partner-app-to-a-posthog-organization-optional) links your app to an organization but doesn't verify it. To ask PostHog to verify your app, open a [support request](https://us.posthog.com/#panel=support%3Asupport%3Alogin%3A%3Atrue) in the app, choosing **Authentication** as the topic.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@MattBro I wonder if when you're back we should build something inside the "verified" section of the UI where they can submit it for review and we can then have an admin UI where we can review these, email kinda sucks, we lose their requests all the time

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ooooo that'd be cool!

MattBro and others added 2 commits October 16, 2026 16:42
The page now says that every app that creates accounts signs, with no
grace dates, so it does not go stale after the grace period ends. The
Node.js examples read the signing key from a name that is not specific
to PostHog.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The in-app support form has no topic picker, so the page only says to
open a support request.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
| Custom rate limits | Ask PostHog, if the top [tier](#your-tier) isn't enough. |
| A Verified badge | Ask PostHog. |

To ask for any of these, open a [support request](https://us.posthog.com/#panel=support%3Asupport%3Alogin%3A%3Atrue) in the app.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Use app.posthog.com rather than hardcoding us here

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

switched all three support links to app.posthog.com: c67dd1d (this PR)

| 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. |
| A personal API key with each provisioned project | Ask PostHog. |
| Paying for your users' PostHog usage | Ask PostHog. Your users' organizations bill to you instead of to them. |

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should probably have a separate section for t his one and mention we'll only enable this for partners which we have a partner agreement with and it requires some kind of volume agreement.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

added a "pay for your users' usage" section saying we only turn it on with a partner agreement that includes a volume commitment, and the table row links to it: c67dd1d (this PR)

…ort link

Paying for users' usage gets its own section, because PostHog turns it on
only under a partner agreement with a volume commitment. Support links go to
app.posthog.com, which sends people to their own region.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@MattBro
MattBro merged commit 49d810b into master Oct 19, 2026
26 checks passed
@MattBro
MattBro deleted the matt/provisioning-signing-required branch October 19, 2026 12:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

content PR only touches files under contents/ docs Improvements or additions to product documentation, "Docs"

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants