Skip to content

docs(id-jag): describe the current xaa setup, plans, and token rules - #21929

Merged
rafaeelaudibert merged 3 commits into
masterfrom
rafa/xaa-docs-current-state
Nov 4, 2026
Merged

rafaeelaudibert merged 3 commits into
masterfrom
rafa/xaa-docs-current-state

Conversation

@rafaeelaudibert

@rafaeelaudibert rafaeelaudibert commented Nov 4, 2026 •

Copy link
Copy Markdown
Member

Executive summary

This PR updates the ID-JAG (XAA) docs to match the product as it is now. PostHog plans to enable XAA settings for all organizations when this PR and PostHog/posthog#128775 merge.

The old page had these errors:

  • It said that XAA is for the Enterprise plan only. Billing gives XAA to the Scale and Enterprise platform add-ons.
  • It described a "Configure XAA (ID-JAG)" modal on each verified domain. The current UI has an XAA authentication section in organization settings, with a domain picker.
  • Its curl example sent no client credentials. The token endpoint refuses that request with invalid_client.
  • It did not list the claims that PostHog requires, such as jti, client_id, and resource, or the 10-minute lifetime limit.
  • It did not explain how PostHog matches an ID-JAG to a user.
  • Some troubleshooting rows were wrong. For example, a user who is not a member gets a specific error, not the generic one.

Changes

  • id-jag.mdx: rewrite the plan callout, requirements, and setup steps for an admin reader. The main page keeps setup, revocation, and the five most common errors.
  • id-jag.mdx: move the technical reference into collapsed FAQ entries at the end: the claims that PostHog checks, user matching, the manual token exchange, token details, and the full error table.
  • agent-discovery.mdx and model-context-protocol/faq.mdx: change "Enterprise plan" to "Scale and Enterprise add-ons".
  • id-jag.mdx and agent-discovery.mdx: remove the beta label. XAA leaves beta when this PR merges and the XAA settings roll out to all organizations.

Not in this PR

  • model-context-protocol/enterprise-managed-authorization.mdx stays unchanged. It still says "Enterprise plan only". The Claude and Okta setup needs a manual test before that page changes.

Dependency

Checks

  • prettier --check passes on the three files. The commit hook ran markdownlint-cli2 --fix.
  • The dev server (pnpm start, Node 22) compiled the page data for all three pages, with the new text.
  • The local dev server could not build the browser bundle because of src/components/Learn/PocketGuides/AioPocketGuide/figures.tsx:63 (changed in Rebuild the AI Observability pocket guide #21849), not this PR.
  • The three pages load on the deploy preview. The ID-JAG page shows all five FAQ entries and its four tables, and an opened FAQ entry shows its table.
  • The preview console shows the same React Burger menu color fix #418/Small fixes for pricing and free trial pages #423 and SVG width errors as the live posthog.com pages, in the same numbers. This PR adds none.
  • check-internal-links (base) failed because its self-hosted runner lost contact while it built master. Other open PRs show the same failure today. check-internal-links (head) passed, and neither link check is required.

🤖 Agent context

  • Written with Claude Code (Claude Opus 5.5). The author directed the work.
  • Each claim comes from the PostHog source: posthog/api/id_jag.py, posthog/api/oauth/views.py, posthog/auth.py, and the settings components. Plan data comes from the live billing catalog.

🤖 Generated with Claude Code

ID-JAG (XAA) is on the Scale and Enterprise platform add-ons, not
Enterprise only. The page also described the old per-domain modal,
showed a token request without client authentication, and left out
the claim rules, user matching, and most error cases.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@rafaeelaudibert rafaeelaudibert self-assigned this Nov 4, 2026
@github-actions

github-actions Bot commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

Deploy preview

Status Details Updated (UTC)
🟢 Ready View preview Nov 04, 2026 01:07AM

Changed pages

Page Source
PostHog MCP FAQ and advanced setup contents/docs/model-context-protocol/faq.mdx
Agent discovery (auth.md) contents/docs/settings/agent-discovery.mdx
ID-JAG (XAA) authentication contents/docs/settings/authentication/id-jag.mdx

@github-actions github-actions Bot added docs Improvements or additions to product documentation, "Docs" content PR only touches files under contents/ labels Nov 4, 2026
@rafaeelaudibert
rafaeelaudibert marked this pull request as ready for review November 4, 2026 00:40
@github-actions

github-actions Bot commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

Vale prose linter → found 5 errors, 33 warnings, 7 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/model-context-protocol/faq.mdx — 5 errors, 22 warnings, 0 suggestions
Line Severity Message Rule
10:71 warning 'untrusted' is a possible misspelling. PostHogBase.Spelling
16:150 warning Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept. PostHogBase.ProductNames
16:165 warning Capitalize 'Product Analytics' for PostHog's product. Use 'product analytics' for the general industry concept. PostHogBase.ProductNames
16:184 warning Capitalize 'Error Tracking' for PostHog's product. Use 'error tracking' for the general industry concept. PostHogBase.ProductNames
16:200 warning Capitalize 'Experiments' for PostHog's product. Use 'experiments' for the general industry concept. PostHogBase.ProductNames
16:231 warning Capitalize 'Surveys' for PostHog's product. Use 'surveys' for the general industry concept. PostHogBase.ProductNames
30:363 warning Capitalize 'Endpoints' for PostHog's product. Use 'endpoints' for the general industry concept. PostHogBase.ProductNames
34:122 warning Capitalize 'Endpoints' for PostHog's product. Use 'endpoints' for the general industry concept. PostHogBase.ProductNames
50:273 warning 'Entra' is a possible misspelling. PostHogBase.Spelling
58:69 warning 'untrusted' is a possible misspelling. PostHogBase.Spelling
62:5 warning 'Using an API key instead of OAuth' heading should be in sentence case, and product names should be capitalized. PostHogBase.SentenceCase
95:30 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
96:25 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
100:20 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
101:15 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
155:124 warning Avoid trivializing words. 'easy to' can sound dismissive to the reader. PostHogDocs.Trivializers
170:122 warning 'Cowork' is a possible misspelling. PostHogBase.Spelling
214:61 warning Use the Oxford comma before 'and' or 'or' in a list of three or more items. PostHogBase.OxfordComma
237:31 warning Capitalize 'Data Warehouse' for PostHog's product. Use 'Data warehouse' for the general industry concept. PostHogBase.ProductNames
243:43 warning Capitalize 'Experiments' for PostHog's product. Use 'experiments' for the general industry concept. PostHogBase.ProductNames
260:31 warning Capitalize 'Session Replay' for PostHog's product. Use 'Session replay' for the general industry concept. PostHogBase.ProductNames
263:31 warning Capitalize 'Customer Analytics' for PostHog's product. Use 'Customer analytics' for the general industry concept. PostHogBase.ProductNames
269:81 warning Don't put a comma after 'e.g.,'. Write 'i.e.' or 'e.g.' with no comma after it. PostHogBase.LatinAbbreviationComma
281:68 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
312:24 warning Use 'PostHog' instead of 'posthog'. Vale.Terms
313:26 warning Use 'PostHog' instead of 'posthog'. Vale.Terms
314:17 warning Use 'PostHog' instead of 'posthog'. Vale.Terms
contents/docs/settings/agent-discovery.mdx — 0 errors, 5 warnings, 0 suggestions
Line Severity Message Rule
6:158 warning Capitalize 'Endpoints' for PostHog's product. Use 'endpoints' for the general industry concept. PostHogBase.ProductNames
17:51 warning Capitalize 'Endpoints' for PostHog's product. Use 'endpoints' for the general industry concept. PostHogBase.ProductNames
69:118 warning Capitalize 'Endpoints' for PostHog's product. Use 'endpoints' for the general industry concept. PostHogBase.ProductNames
94:74 warning Capitalize 'Endpoints' for PostHog's product. Use 'endpoints' for the general industry concept. PostHogBase.ProductNames
94:234 warning 'hardcoding' is a possible misspelling. PostHogBase.Spelling
contents/docs/settings/authentication/id-jag.mdx — 0 errors, 6 warnings, 7 suggestions
Line Severity Message Rule
10:163 warning 'Entra' is a possible misspelling. PostHogBase.Spelling
81:49 warning 'IdP's' is a possible misspelling. PostHogBase.Spelling
82:61 warning 'IdP's' is a possible misspelling. PostHogBase.Spelling
105:28 suggestion Address the reader directly. Use 'you' instead of 'the user'. PostHogDocs.DirectAddress
116:122 suggestion Address the reader directly. Use 'you' instead of 'the user'. PostHogDocs.DirectAddress
117:61 suggestion Address the reader directly. Use 'you' instead of 'The user'. PostHogDocs.DirectAddress
122:4 warning 'FAQ' heading should be in sentence case, and product names should be capitalized. PostHogBase.SentenceCase
130:102 warning 'IdP's' is a possible misspelling. PostHogBase.Spelling
135:35 suggestion Address the reader directly. Use 'you' instead of 'the user'. PostHogDocs.DirectAddress
136:13 suggestion Address the reader directly. Use 'you' instead of 'The user'. PostHogDocs.DirectAddress
142:22 warning 'IdP's' is a possible misspelling. PostHogBase.Spelling
149:118 suggestion Address the reader directly. Use 'you' instead of 'the user'. PostHogDocs.DirectAddress
201:43 suggestion Address the reader directly. Use 'you' instead of 'The user'. PostHogDocs.DirectAddress

rafaeelaudibert and others added 2 commits November 3, 2026 21:42
ID-JAG (XAA) leaves beta when the XAA settings roll out to all
organizations.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Admins configuring XAA need the setup steps, revocation, and the common
errors. The claim rules, user matching, manual token exchange, token
details, and full error table now sit in collapsed FAQ entries at the
end of the page.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@github-actions

github-actions Bot commented Nov 4, 2026

Copy link
Copy Markdown
Contributor

Bundle report

Total JS (gzip)

11.71 MiB (+0.1 KiB / +0.0%)

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

Entrypoint Eager size Budget Modules
✅ app 9.94 MiB (no change) report-only 1024
Largest modules in the app closure
Module Size
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 839.5 KiB
./src/components/Stickers/Stickers.tsx 696.4 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
./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 + 126 modules 287.2 KiB
./node_modules/.pnpm/cloudinary-core@2.14.0_lodash@4.17.21/node_modules/cloudinary-core/cloudinary-core.js 281.9 KiB
./src/components/SearchUI/index.tsx + 87 modules 273.1 KiB
./gatsby-browser.tsx + 59 modules 259.1 KiB
./node_modules/.pnpm/@posthog+brand@0.13.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/construction-1.mjs 248.5 KiB
./src/components/Pricing/PricingSlider/Slider.tsx + 87 modules 240.2 KiB
./node_modules/.pnpm/@posthog+brand@0.13.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/construction-2.mjs 228.2 KiB
./node_modules/.pnpm/@posthog+brand@0.13.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/magnifying-glass.mjs 221.7 KiB
./src/hooks/skills.tsx + 2 modules 150.7 KiB
./src/hooks/useProduct.ts + 9 modules 149.9 KiB
./src/components/Icons/Icons.tsx 147.4 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).

@rafaeelaudibert
rafaeelaudibert merged commit 47577fa into master Nov 4, 2026
25 of 29 checks passed
@rafaeelaudibert
rafaeelaudibert deleted the rafa/xaa-docs-current-state branch November 4, 2026 14:41
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.

1 participant