docs: document Personal Access Tokens - #147
Conversation
pipeshub-ai's Personal Access Token feature (self-service, scoped, revocable credentials that act as their creator) shipped with no documentation here, even though the sibling OAuth Applications feature has a full guide. Meanwhile mcp/overview.mdx and mcp/local-server.mdx already referenced a generic "Bearer token" placeholder with no guidance on where to get one — exactly what a PAT is for. Adds developer/personal-access-tokens.mdx (creation, usage, revocation, the new admin list/revoke API, full endpoint reference, FAQ), and updates the two MCP pages to point at it as the recommended bearer-token source for connecting an MCP client.
|
Warning Review limit reached
Next review available in: 53 minutes You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (2)
📝 WalkthroughWalkthroughAdded a Developer documentation page for Personal Access Tokens. The page covers creation, expiry, scopes, bearer-token usage, revocation, administration, security, APIs, and FAQs. MCP documentation now recommends PATs alongside OAuth credentials. ChangesPersonal Access Token documentation
Estimated code review effort: 3 (Moderate) | ~20 minutes Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@mcp/overview.mdx`:
- Around line 20-24: The PAT guidance in the Note should not claim it works in
any client configuration. Update the Note to direct PAT users specifically to
the Local Server (Stdio) --bearer-auth flow, while preserving the OAuth guidance
for shared or app-based integrations.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 07f5fef2-1684-4869-91d9-c6b7e7cb0543
📒 Files selected for processing (4)
developer/personal-access-tokens.mdxdocs.jsonmcp/local-server.mdxmcp/overview.mdx
The MCP overview's PAT note claimed a personal access token works as
YOUR_BEARER_TOKEN "in any client config on this page" — but every
remote client guide linked from that page (Cursor, Claude Code, Gemini
CLI, Claude.ai, LibreChat) is an OAuth client_id/secret flow with no
bearer-token option, verified against each guide's actual config.
Tightened the note to point at what does accept a bearer token: /mcp
directly, the Local Server (Stdio) package, or a self-configured
client. Also updated the page's frontmatter description, which still
said "using OAuth" with no mention of the PAT path.
On the PAT page itself: documented the actual PIPESHUB_MCP_URL /
PIPESHUB_MCP_TOKEN paste block the create panel emits (not a generic
raw token), the admin list's real { data, pagination } response shape
with the ownerDeleted field (distinct from the self-list's flat
{ tokens }), and request bodies for create/revoke to match the depth
of the existing oauth2.mdx guide.
|
Addressed the review (CodeRabbit + a second pass): Fixed — #1, the real issue:
Nice-to-haves — added:
Screenshots remain a known gap (noted in the PR description) — no live instance with seeded data to capture from this environment.
|
- Admin response-shape callout was a <Warning> for something informational, not hazardous — switched to <Note>, matching how the rest of this repo uses the two. - Split the MCP overview's OAuth-vs-PAT note into two sentences instead of one long compound one. - Connected the create panel's paste block to the usage section right below it: PIPESHUB_MCP_TOKEN is the same value passed to --bearer-auth / Authorization: Bearer.
shekharkadyan
left a comment
shekharkadyan
left a comment
There was a problem hiding this comment.
Reviewed against current pipeshub-ai source (PAT worktree) and the QM integration we just measured. The page is needed and most of it is right — PAT vs OAuth, phpat_ as a scanner prefix, 30-day default, one-time display, and the overview no longer telling people a PAT works in Cursor.
Two accuracy issues to fix before merge. The rest is optional.
Looks good (verified)
- Default 30-day expiry matches
create-pat-panel.tsx(DEFAULT_EXPIRY_DAYS = 30) and the API. - Default scopes = full
MCP_SCOPESis honest: the panel pre-selects every scope (create-pat-panel.tsx:108) and omittingscopeson create over-grants the same set (pat.service.ts). - New token matches
en-US.json(workspace.personalAccessTokens.newToken). - Admin list/revoke returning 400 for non-admins is unusual (usually 403) but correct —
userAdminCheck.ts:25throwsBadRequestError('Admin access required'). - Nav under Developer, next to OAuth, is the right place.
Nits / follow-ups, not blocking
- UI path Workspace-settings → Personal Access Tokens matches the sibling
oauth2.mdx. Live sidebar is Developer Settings → Personal Access Tokens; New token is the button. Fine. - Screenshots still missing — already noted in the PR body.
- After Use with QM lands, add a reciprocal sentence here so QM operators are not sent to the MCP paste block. I opened that page as a sibling PR.
client_credentials was described as acting as the app's owner. It has no user identity at all: the controller passes `null // No user` into generateTokens (oauth.provider.controller.ts:534-536) and the service falls back to the client id (oauth_token.service.ts:78). The owner's name is copied for display, not authenticated. That distinction is the reason this page exists, so getting it backwards undercut the whole comparison. A PAT was described as working anywhere a session token would. It reaches the same endpoints, but session tokens skip scope checks entirely (require-scopes.middleware.ts:37) while PATs are enforced against the scopes granted. Saying they are equivalent removes the reason to grant fewer scopes. The create-token paste block uses PIPESHUB_MCP_TOKEN / PIPESHUB_MCP_URL, which is right for MCP clients and wrong for QM — it wants PIPESHUB_TOKEN and PIPESHUB_BASE_URL on two keychain entries. Pasting the block there fails looking like a missing variable rather than a misnamed one, so the page now says so. Left as plain text, not a link: /mcp/qm arrives in #149. Added the recovery line for a phpat_ token returning 401 on an instance that predates the prefix-stripping fix, since that failure used to surface as an empty result rather than an auth error.
|
All four addressed in
A PAT is not equivalent to being logged in. Verified: The paste block is wrong for QM. Added a note under it naming Older instances and The CodeRabbit comment about restricting PAT guidance to bearer-auth clients was already handled in |
2 participants
Summary
PipesHub's Personal Access Token feature (pipeshub-ai#2933) shipped with no documentation here — despite the sibling OAuth Applications feature having a full guide with screenshots.
mcp/overview.mdxandmcp/local-server.mdxalso already referenced a genericYOUR_BEARER_TOKENplaceholder with no guidance on where to actually get one, which is exactly what a PAT is for.What changed
developer/personal-access-tokens.mdx— creation, usage (including MCP), revocation, the admin list/revoke API, full endpoint reference, security notes, and FAQ. Mirrors the structure/tone ofdeveloper/oauth2.mdx.mcp/overview.mdxandmcp/local-server.mdx— point at PATs as the recommended bearer-token source, since they're simpler than the OAuth-app flow for a single person's own tooling.docs.json.Notes
developer/oauth2.mdxpage has real screenshots (/images/developer/oauth2/*.png); this page would benefit from equivalent/images/developer/personal-access-tokens/*.pngshots of the list/create panel if someone wants to add them.npx mintlify broken-links— 9 pre-existing broken links elsewhere in the repo, none introduced by this change.phpat_prefix,400for non-admin on the admin routes, deleted-user rejection, 100-item self-list cap, paginated admin list) verified directly against the currentpipeshub-aisource, not guessed.🤖 Generated with Claude Code
Summary by CodeRabbit