Skip to content

docs(toolbar): note that authorized URLs must match the site origin including the port#16479

Open
singhvishalkr wants to merge 1 commit intoPostHog:masterfrom
singhvishalkr:docs/toolbar-authorized-urls-port-note
Open

docs(toolbar): note that authorized URLs must match the site origin including the port#16479
singhvishalkr wants to merge 1 commit intoPostHog:masterfrom
singhvishalkr:docs/toolbar-authorized-urls-port-note

Conversation

@singhvishalkr
Copy link
Copy Markdown
Contributor

Problem

Users who add an entry to "Authorized URLs for Toolbar" that does not match their site's actual origin (specifically, the port) often see the toolbar silently fail to load. This has tripped up at least one user for ~1 hour of debugging (see #9789).

Looking at checkUrlIsAuthorized, matching uses parsedUrl.protocol + '//' + parsedUrl.host, and URL.host includes the port when one is present. So http://localhost and http://localhost:3000 are not a match. The previous docs did not call this out.

Fix

Adds two pieces of guidance to contents/docs/toolbar/index.mdx:

  1. A short callout under How to launch the toolbar telling users the authorized URL must match the site origin exactly (including port), with a concrete local-dev example.
  2. A troubleshooting entry (#### 3. The authorized URL does not match your site's origin (including port)) that lists the three most common mismatch shapes (missing port, explicit default port like :443, trailing path/query).

No behaviour changes -- docs only.

Closes

Closes #9789.

How I tested

  • Read authorizedUrlListLogic.ts to confirm origin matching uses protocol + host (host includes port).
  • Rendered the MDX locally to confirm the note and the new #### heading sit in the expected positions within the toolbar page.

…ncluding the port


Adds a note under 'How to launch the toolbar' and a troubleshooting entry
explaining that the authorized URL's origin (protocol + host + port) must
match the site's origin exactly. A missing or extra port is a common silent
cause of the toolbar not appearing.

Closes PostHog#9789.
@singhvishalkr singhvishalkr force-pushed the docs/toolbar-authorized-urls-port-note branch from 5d0480b to 599f513 Compare April 21, 2026 11:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Toolbar docs: Add a section to this article and advise against using port numbers in "Authorized URLs for Toolbar" section

1 participant