Reporter auth

Reporter auth controls who is allowed to file a report through the widget, and what identity gets attached to it. It’s separate from your Patchrooms dashboard login — this is about the reporter, the person (or agent) using the widget on your site.

Modes

A project has one or more active modes, set in the dashboard under the project’s Settings tab:

Mode	What it means
anonymous	No identity required. Anyone can file a report.
email	The reporter types an email address. Unverified — it’s a label, not a login.
oauth	The reporter signs in with an OAuth provider (Google, GitHub, or a custom SSO provider your org configured).

At least one mode must stay enabled. Modes aren’t exclusive — enabling more than one offers the reporter a choice.

The gate

If a project’s only enabled mode is anonymous, the widget never interrupts — reports go straight through. As soon as email or oauth is also enabled, the widget shows a gate the first time someone opens the panel, with one button per available option:

• Continue as guest — if anonymous is enabled.
• Continue with email — if email is enabled; reveals an email field.
• Continue with <Provider> — one button per available OAuth provider, if oauth is enabled.

The reporter’s choice is remembered in localStorage (per project key), so the gate doesn’t reappear on later visits.

OAuth providers

Two layers decide which OAuth buttons a reporter actually sees:

1. Built-in providers — Google and GitHub, using Patchrooms’s own OAuth app. An org opts into either (or both) under Settings → Widget OAuth providers.
2. Custom SSO — your org’s own OpenID Connect identity provider (Okta, Auth0, Keycloak, Azure AD, or a Google Workspace app with your own client), configured per organization.

Both apply across every project in the org; a project’s oauth mode just turns the whole category on or off for that project.

Setting up a custom SSO provider

In Settings → Custom SSO (org admin/owner only), add a provider:

Field	Notes
Name	Shown on the gate button, e.g. “Continue with Okta”.
Key	URL-safe id, auto-slugged from the name. Part of the callback URL.
Issuer URL	Your IdP’s OIDC issuer, e.g. https://your-org.okta.com. Discovery (/.well-known/openid-configuration) is resolved from this at auth time — no separate authorize/token URLs to fill in.
Client ID	From your IdP app registration.
Client secret	From your IdP app registration. Write-only — Patchrooms never displays it again after saving; to change it, remove the provider and add it again.

Register this callback URL with your IdP as the redirect URI:

https://room.patchrooms.com/ingest/oauth/org/<orgId>/<key>/callback

<orgId> and <key> are shown next to each configured provider so you can copy the exact URL. An org can configure up to 5 custom SSO providers. The scope requested is fixed: openid email profile.

Caution

Client secrets are stored server-side and are never returned by the API or shown in the dashboard after the initial save.

Bridging an already-signed-in host user

If your own app already knows who the user is, you can skip the gate entirely and hand that identity straight to the widget — useful when the widget is embedded in a product you control and re-authenticating would be redundant (the Patchrooms dashboard does exactly this for its own dogfooded widget).

1. From your backend or a page where the user has a live Patchrooms dashboard session, call:

   GET https://room.patchrooms.com/auth/reporter-token?projectKey=pr_xxx

   with the session cookie attached. It returns:

   { "token": "…", "profile": { "email": "…", "name": "…", "avatarUrl": "…" } }

2. Pass it to init():

   Patchrooms.init({
     projectKey: 'pr_xxx',
     reporter: { token, profile },
   });

reporter skips the gate outright and overwrites whatever choice is cached in localStorage for that project — the host is the source of truth. Re-pass it on every init() call to keep it in sync (e.g. after the host user logs out). See InitOptions.reporter for the full type.

Note

This endpoint mints a token tied to a Patchrooms dashboard session, scoped to one projectKey. It’s meant for first-party surfaces that already share that session — not a general SSO bridge for arbitrary third-party sites.

How a report gets its author

Every report carries an author — derived automatically from whatever identity signal is present, in this priority order:

1. OAuth reporter — signed in via the gate or the token bridge.
2. Email reporter — typed into the gate’s email field.
3. Verified identity — an x-alphabug-identity token, if your integration sets one.
4. Device — a persistent anonymous id the widget generates once per browser, used when no stronger identity is available.
5. Otherwise the report has no author (fully anonymous, old SDK versions without a device id).

Reports filed through the MCP server get a fifth kind, agent, labelled from the calling agent’s introduce name. See Reports → Author for how this shows up in the dashboard.