API tokens

A personal access token (PAT) is a credential you mint in the dashboard and use to authenticate against the WebPinch REST API and the MCP server. PATs look like wp_pat_… and are tied to your user account.

Two token types

WebPinch has two distinct credential systems. Don’t mix them up.

	Personal access token (PAT)	Project guest token
Format	`wp_pat_` + 32 chars	21-char `nanoid`
Tied to	Your user account	A specific project
Scope	Everything you can see in the dashboard	Submit guest tasks to one project
Where it’s used	REST API (`/api/v1/*`), MCP server, signed-in extension features	Public Chrome extension widget, embed widget
Mint at	`Dashboard → API Tokens`	`Project Settings → Integration`

If you’re unsure which one you need: it’s almost always a PAT. Guest tokens exist for the public widget flow.

Scopes

A PAT carries a fixed list of scopes set at creation time. Scopes can’t be edited — to change them, mint a new token and revoke the old.

Scope	Grants
`tasks:read`	List + read tasks, comments, checklists, attachments, activity
`tasks:write`	Create/update tasks, post comments, edit checklists
`projects:read`	List + read projects, columns, members
`audits:read`	List + read site audits
`audits:run`	Start / re-analyze site audits
`stats:read`	Read dashboard stats

Pick the minimum set of scopes you need. A token used by a CI job that only opens issues should be tasks:write only — not audits:run, even if you have permission.

Authorization model

A PAT inherits your access. On every request:

The token is looked up by hash.
WebPinch resolves your accessible projects: org membership (any project where Project.orgId belongs to an org you’re an active member of) plus any project where you’re a direct member.
Every project-scoped query is filtered by that list.

There is no way for a token to access a project you can’t see in the dashboard. If you’re removed from an org or project, your tokens immediately stop seeing it (no caching).

Tokens carry your full account access. Treat a PAT like a password. Anyone with the value can do anything in WebPinch that you can do (within the scopes you granted it).

Mint a token

Open the tokens page

Dashboard → API Tokens (or go directly to /dashboard/settings/api).

Click New token

Give it a memorable name describing where it’ll be used:

Claude Code on MacBook
CI deploy webhook
Notion integration

Pick scopes

Tick only what’s needed. Default suggestion is tasks:read + projects:read.

Optional expiration

Pick 30 days, 60 days, 90 days, 1 year, or No expiration. Shorter is safer; longer is less hassle. Tokens for unattended automation usually want no expiration plus a calendar reminder to rotate.

Copy the token immediately

The plaintext value is shown once, in a green banner at the top of the page. Reload the page and it’s gone forever. WebPinch only stores its hash.

Use a token


curl https://www.webpinch.com/api/v1/me \
  -H "Authorization: Bearer wp_pat_..."

X-Webpinch-Token: wp_pat_… is also accepted as an alternate header.

For full reference, see REST API and MCP server.

Storage and security

Hashed at rest. WebPinch stores SHA-256(token) in MongoDB and the prefix (first 12 chars) for display. The plaintext is never persisted.
One-shot reveal. The full token is only ever shown immediately after creation.
Token in transit. Always use HTTPS. PATs sent over plain HTTP can be intercepted.
Don’t commit tokens to source control. Use environment variables. The MCP server takes its token via WEBPINCH_TOKEN env var for exactly this reason.

Revoke a token

In the tokens page, click Revoke on the token row. Effect is immediate — the next request using that token returns 401 INVALID_TOKEN.

If you suspect a token has leaked:

Revoke first

Cut access immediately, even before investigating.

Mint a replacement

With the same scopes if you need to keep the integration running.

Update consumers

Swap the new value into wherever the old token was used (~/.claude.json, CI secrets, env files).

Audit usage

Check the Last used column on existing tokens to see what was active recently.

PAT-can’t-mint-PATs rule

The /api/auth/tokens endpoint that mints and lists tokens rejects PAT auth with 403 Forbidden. Only your dashboard cookie session can manage tokens. This means a stolen PAT can’t escalate by minting another PAT — to get more access, an attacker would need to log in as you in a browser.