Projects & team

ProjectsCopy Anchor Link

A project is one website (or one environment of it). It has its own widget key, allowed sites, widget and capture settings, integrations and retention. Create one from Projects › New project; give it a name and the site it runs on.

Each project has a public key (pk_…). It is meant to be public — it goes in the snippet on your site. What protects the project is the list of allowed sites and the rate limit, not the key.

Allowed sites (origins)Copy Anchor Link

The widget is accepted only from the sites on the project's list; requests from any other Origin get 403 ORIGIN_NOT_ALLOWED. Add up to 50 patterns, each a hostname with an optional port and an optional leading *.:

Hostnames are compared exactly, so example.com never matches evil-example.com. A scheme or path you paste (https://example.com/shop) is ignored. Add localhost:<port> while you develop.

Project settings tabsCopy Anchor Link

The project header also links to the project's Rounds (review rounds), Pages (page review) and Open inbox.

Project settings are configuration, so only organisation owners and admins can change them — allowed sites, widget and capture settings, panel actions, issue trackers, privacy, the signing and identity secrets, the key and archiving. Members and viewers see the tabs read-only (without the Danger zone), with a note saying why; webhook action URLs are hidden from them. The server enforces the same rule: a change from anyone else is answered 403 ADMIN_REQUIRED.

Privacy & dataCopy Anchor Link

Creating a projectCopy Anchor Link

Admins create projects (Projects › New project, or the + next to Projects in the sidebar): a name, the site's domain, and What is this site for?

The API takes the same choice as preset: "public-site" | "review" on POST /api/projects. The new project opens on its Install tab.

Refused sitesCopy Anchor Link

When a page that isn't on the allowed list loads the widget, the server refuses it (403 ORIGIN_NOT_ALLOWED) and remembers the origin. The Install tab lists the last ten — "Blocked a request from https://www.example.com, 2 min ago" — with an Allow button that adds the site and clears it from the list.

Review linksCopy Anchor Link

A review link lets a client or reviewer use the widget on your site without an account, even where the project's visibility rules hide it from everyone else (BugPin-style guest review).

1. Open the project's Review links tab and choose New link.
2. Give it a name (for example "Acme sign-off round"), the page it opens (one of the project's allowed sites) and when it stops working (7, 30 or 90 days, or never).
3. Copy the link: it is shown once, because only a hash of its pinwren_review token is stored. Send it to your reviewer.

Whoever opens the link sees the widget for the rest of that browser tab. Before they send a comment or a bug report the widget asks for their name (the email is optional, and gets them the reporter emails you have switched on). Everything they send is marked with the link's name:

• the item's Details tab shows Source: Review link · Acme sign-off round, and its timeline reads "Gina reported this via review link Acme sign-off round";
• Filter › Review link in the inbox (or ?review=<link id>) lists only what came through one link;
• the Review links tab shows how many items came through each link and when it was last used — the count opens the filtered inbox.

Revoke switches a link off at once; items already sent keep their source. A revoked or expired link no longer shows the widget, and reports sent with it are accepted without a source. When pins are private (Show existing pins to visitors off on the Privacy & data tab), each guest sees only what they sent themselves.

Review links are for admins. The widget's token check is rate-limited per visitor, and new links per workspace (50 an hour).

Export and erasureCopy Anchor Link

• Export this project (Privacy & data) prepares a zip in the background: feedback.json (every report with its comments, activity and labels), project.json (settings, without secrets), labels.json and every screenshot, attachment and replay under assets/. The download is kept for 7 days; a new export replaces it. Files beyond 512 MB in all are left out and counted in README.txt.
• Erase a reporter's data handles a deletion request: enter the email a reporter used in the widget, Find data shows what would go (reports, replies on other reports, logged emails), and Erase removes it from every project of the workspace, files included. A record that an erasure happened (who, when, how much — not the address) is listed under the card.

Both are for workspace admins (GET/POST /api/projects/:id/export, GET /api/projects/:id/export/download, POST /api/privacy/erase { email, dryRun? }).

Rotating the key and archivingCopy Anchor Link

• Rotate the project key issues a new pk_…. The old one stops working at once, so the widget on your site stops until you update the snippet.
• Archive hides the project from your lists and stops its widget key; nothing is deleted. Restore it from the same tab.

Users and rolesCopy Anchor Link

Your workspace holds the projects and the people who triage them. Admins add people from Settings › Users: Add user creates the account at once (name, email, password, role), and Invite by email sends a link to join. Roles are Admin, Editor and Viewer:

The owner is the Admin who created the workspace; ownership moves in Settings › Workspace. See accounts, users and workspaces for adding users, password resets, two-factor sign-in, your profile and switching workspaces.

A workspace can send PINWREN_INVITES_PER_HOUR invitations an hour (default 30); beyond that, inviting is refused until the hour is up. Sign-up on a self-hosted instance is closed to everyone but invited people once the first account exists (unless the operator sets PINWREN_DISABLE_SIGNUP=false), so Add User or an invitation is how people join.

Viewers get read-only screens, and the server enforces it: any change they try is answered 403 READ_ONLY_ROLE, and anything an Editor's role doesn't allow is answered 403 FORBIDDEN_ROLE. Viewers can still mark notifications read, set their notification preferences, edit their own profile, create their own API tokens (which are read-only too) and keep personal saved views.

The people who leave feedback through the widget are not members and need no account; they are unlimited.

BrandingCopy Anchor Link

Settings › Branding (admins) sets the workspace's product name (up to 40 characters, replacing "Pinwren"), logo (PNG, JPEG or WebP up to 512 KB; SVG is refused) and accent colour. They apply to the dashboard header, buttons and links, and to every email the workspace sends.

The widget's own branding — hiding "Powered by Pinwren", the dialog accent and a logo in the report form — is set per project under Widget; see configuration.

Email templatesCopy Anchor Link

Settings › Notifications › Email templates lets admins rewrite every email the workspace sends, to the team and to reporters. Each template is a subject and a Markdown body with {{variable}} placeholders; raw HTML is shown as text, never rendered, and variables are escaped. Every template has a live preview, Send me this email (a test to your own address only — at most 10 an hour per person and 30 per workspace) and Reset to default. New-report and assignment emails also show the report's screenshot and facts under your text, whatever the template says.

Which of these go out, and to whom, is set in the other Notifications tabs — see notifications. Password reset and email verification emails use fixed wording.

Variables:

A placeholder that isn't available in a template is rejected when you save.

Instance settingsCopy Anchor Link

Three pages belong to whoever runs the server — the instance admins: the first account created on the server, anyone an instance admin names in Settings › Security › Instance administrators, and the accounts whose addresses are in PINWREN_ADMIN_EMAILS (see the first account).

• Settings › Email — the SMTP server, Send test email (tests the form before you save it) and Recent deliveries, the log of what was sent, skipped or failed. See email.
• Settings › Security — the instance administrators, the sign-in methods (email sign-in links and passkeys on or off; whether Google and GitHub are configured, with their callback URLs; see Other ways to sign in), session lifetime (1–90 days, for new sign-ins), whether HTTPS is enforced and whether the server trusts reverse proxies and how many hops (both read-only, set by PINWREN_ENFORCE_HTTPS and PINWREN_TRUST_PROXY), and the daily update check with Check now.
• Settings › Licence — install or remove an Enterprise licence. See licensing.

A field set by an environment variable is shown read-only, and changing it through the API returns 409 SETTING_LOCKED.

Exporting feedbackCopy Anchor Link

Visitors and team members can export the comments of a page, or every page they can see, as CSV or JSON from the widget's side panel — see comments. For scripts and other tools, use the REST API.

A review round exports as CSV or PDF.