docs: clarify CIMD redirect_uris can be cross-domain

[MattBro]

Changes

Clarifies the OAuth CIMD docs (/docs/api/oauth) on two points that came up in a partner support ticket:

• redirect_uris may be on a different domain than your client_id – they only need to be listed in the metadata document. The old example used the same domain for both, which led a partner to assume same-domain was required. It isn't – PostHog does an exact-match check against the listed URIs, with no origin comparison against the client_id.
• Added a note that PostHog caches the metadata document per your Cache-Control: max-age, so a newly added redirect URI won't take effect until the cached copy's TTL elapses. This was the actual root cause of the partner's "redirect URI mismatch" (they added the cross-domain URI after their client was first cached).

Both statements were verified against the implementation in the posthog monorepo (CIMD validation stores redirect_uris verbatim with no domain check; the authorize flow uses django-oauth-toolkit's exact-match redirect_uri_allowed; https is required except for loopback).

Checklist

• I've read the docs style guide
• 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 (n/a – no move)

🤖 Generated with Claude Code

[github-actions]

Vale prose linter → found 0 errors, 27 warnings, 0 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/api/oauth.mdx — 0 errors, 27 warnings, 0 suggestions

Line	Severity	Message	Rule
2:8	warning	'OAuth' is a possible misspelling.	PostHogBase.Spelling
7:19	warning	'OAuth' is a possible misspelling.	PostHogBase.Spelling
7:195	warning	'OAuth' is a possible misspelling.	PostHogBase.Spelling
9:4	warning	'OAuth server endpoints' heading should be in sentence case, and product names should be capitalized.	PostHogBase.SentenceCase
9:4	warning	'OAuth' is a possible misspelling.	PostHogBase.Spelling
9:17	warning	Capitalize 'Endpoints' for PostHog's product. Use 'endpoints' for the general industry concept.	PostHogBase.ProductNames
11:11	warning	'OAuth' is a possible misspelling.	PostHogBase.Spelling
11:17	warning	Capitalize 'Endpoints' for PostHog's product. Use 'endpoints' for the general industry concept.	PostHogBase.ProductNames
21:4	warning	'Client ID Metadata Document (CIMD)' heading should be in sentence case, and product names should be capitalized.	PostHogBase.SentenceCase
23:74	warning	'OAuth' is a possible misspelling.	PostHogBase.Spelling
25:40	warning	'OAuth' is a possible misspelling.	PostHogBase.Spelling
28:128	warning	'OAuth' is a possible misspelling.	PostHogBase.Spelling
52:10	warning	'OAuth' is a possible misspelling.	PostHogBase.Spelling
58:21	warning	'OAuth' is a possible misspelling.	PostHogBase.Spelling
70:27	warning	Capitalize 'Endpoints' for PostHog's product. Use 'endpoints' for the general industry concept.	PostHogBase.ProductNames
74:34	warning	'OAuth' is a possible misspelling.	PostHogBase.Spelling
79:21	warning	'OAuth' is a possible misspelling.	PostHogBase.Spelling
91:20	warning	'OAuth' is a possible misspelling.	PostHogBase.Spelling
95:34	warning	'OAuth' is a possible misspelling.	PostHogBase.Spelling
98:1	warning	'OAuth' is a possible misspelling.	PostHogBase.Spelling
102:30	warning	'OAuth' is a possible misspelling.	PostHogBase.Spelling
108:220	warning	Use 'PostHog' instead of 'posthog'.	Vale.Terms
114:9	warning	'OAuth' is a possible misspelling.	PostHogBase.Spelling
125:4	warning	'OAuth' is a possible misspelling.	PostHogBase.Spelling
126:4	warning	'OAuth' is a possible misspelling.	PostHogBase.Spelling
127:4	warning	'OAuth' is a possible misspelling.	PostHogBase.Spelling
128:4	warning	'OAuth' is a possible misspelling.	PostHogBase.Spelling

[github-actions]

Deploy preview

Status	Details	Updated (UTC)
🟢 Ready	View preview	Jul 06, 2026 07:57PM

[github-actions]

Bundle report

Total JS (gzip)

6.29 MiB (+0.0 KiB / +0.0%)

Eager graph (static-import closure per entrypoint)

Entrypoint	Eager size	Budget	Modules
✅ app	24.22 MiB (+1.0 KiB / +0.0%)	report-only	5516

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	707.7 KiB
./src/components/Stickers/Stickers.tsx	696.4 KiB
./.cache/caches/gatsby-plugin-mdx/mdx-scopes-dir/31a094f140f119e73085d847ae81b99b.js + 2 modules	586.5 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/@codemirror+view@6.38.2/node_modules/@codemirror/view/dist/index.js	458.1 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+icons@0.36.6_react-dom@18.3.1_react@18.3.1__react@18.3.1/node_modules/@posthog/icons/dist/posthog-icons.cjs.js	364.8 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
./src/hooks/useCustomers.tsx + 54 modules	353.9 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/cloudinary-core@2.14.0_lodash@4.17.21/node_modules/cloudinary-core/cloudinary-core.js	281.9 KiB
./src/components/ProductComparisonTable/index.tsx + 116 modules	267.6 KiB
./node_modules/.pnpm/@codesandbox+sandpack-react@2.20.0_react-dom@18.3.1_react@18.3.1__react@18.3.1/node_modules/@codesandbox/sandpack-react/dist/index.mjs	266.6 KiB
./node_modules/.pnpm/d3@7.9.0/node_modules/d3/src/index.js + 208 modules	247.4 KiB
./src/components/Pricing/PricingSlider/Slider.tsx + 87 modules	239.9 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.

[rafaeelaudibert]

As a follow-up, explain how people can define localhost with a known port OR specify no port to support dynamic port assignment.

[MattBro]

Folded the follow-up in rather than deferring – added a paragraph on loopback port handling: register localhost/127.0.0.1 without a port for dynamic ports, or with an explicit port for a fixed one. Worth flagging one subtlety I verified in the code while writing it: a registered localhost URI enforces the exact port, but 127.0.0.1/::1 ignore the port entirely (django-oauth-toolkit's RFC 8252 handling), so those match any port even when you register one.