pipeshub-ai · rish664 · Aug 15, 2026 · Aug 10, 2026 · Aug 10, 2026 · Aug 10, 2026
diff --git a/developer/personal-access-tokens.mdx b/developer/personal-access-tokens.mdx
@@ -0,0 +1,194 @@
+---
+title: "Personal Access Tokens"
+description: "Create long-lived, scoped, revocable credentials that act as you — the recommended way to connect external agents and scripts to PipesHub"
+icon: "id-badge"
+---
+
+A **Personal Access Token (PAT)** is a long-lived, scoped, revocable credential that you create for yourself. Unlike a session token, it doesn't expire after a day. Unlike an [OAuth 2.0 Application](/developer/oauth2), it authenticates as **you** — every request made with it respects your own per-user permissions, not an app's.
+
+Use a PAT when you want to connect something to PipesHub programmatically — most commonly, an MCP client (see [MCP Server Overview](/mcp/overview)) — without setting up an OAuth app or scraping a short-lived session token.
+
+<Note>
+  PATs are self-service: **any org member** can create their own, no administrator involvement required.
+</Note>
+
+---
+
+## Personal Access Tokens vs. OAuth Applications
+
+| | Personal Access Token | OAuth 2.0 Application |
+|---|---|---|
+| **Acts as** | You, the creator | The app itself (or, for `client_credentials`, the app's owner) |
+| **Who can create one** | Any org member | Administrators only |
+| **Setup** | One click, no redirect URIs | Register an app, configure redirect URIs and grant types |
+| **Best for** | Personal scripts, MCP clients, quick integrations | Third-party apps, multi-user integrations, machine-to-machine services |
+
+If you're connecting your own tooling and want it to see exactly what you can see, use a PAT. If you're building something other people in the org will authorize separately, use an [OAuth Application](/developer/oauth2).
+
+---
+
+## Creating a Personal Access Token
+
+### Step 1: Open Personal Access Tokens
+
+1. Sign in to your PipesHub account
+2. Navigate to **Workspace-settings**
+3. Select **Personal Access Tokens** under the **Developer Settings** section
+
+### Step 2: Create a New Token
+
+Click **New token** and fill in:
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| **Name** | Yes | A label to help you recognize the token later (e.g. `Claude Desktop`, `CI script`), 1–100 characters. |
+| **Expiry** | No | `30`, `90`, or `365` days, or `Never`. Defaults to **30 days** if not set — a token minted without a second thought shouldn't default to the longest lifetime. |
+| **Scopes** | No | Which permissions the token carries. Defaults to your instance's full configured MCP scope set if none are selected. Use **Select All** / **Clear all** to toggle every scope at once. |
+
+<Warning>
+  A token with `Never` expiry has no automatic cutoff. Prefer a bounded expiry unless you have a specific, ongoing reason not to — you can always create a new token later.
+</Warning>
+
+### Step 3: Copy the Token
+
+PipesHub generates the token and shows it to you **exactly once**:
+
+```
+phpat_eyJhbGciOiJIUzI1NiIs...
+```
+
+<Warning>
+  Copy and store the token immediately. Only its hash is stored server-side — if you lose it, you'll need to revoke it and create a new one.
+</Warning>
+
+<Tip>
+  The `phpat_` prefix is intentional and display-only — it makes personal access tokens easy to recognize in logs, config files, and secret-scanning tools, unlike a bare JWT. It's stripped automatically before the token is verified, so nothing else about how you use the token changes.
+</Tip>
+
+---
+
+## Using a Personal Access Token
+
+Send it as a standard bearer token on any authenticated PipesHub API request, including the [MCP endpoint](/mcp/overview):
+
+```bash
+curl -X POST https://your-pipeshub-instance.com/mcp \
+  -H "Authorization: Bearer phpat_YOUR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
+```
+
+For the local stdio MCP server, or any MCP client that takes a bearer token (see [Local Server (Stdio)](/mcp/local-server)), pass the PAT as `YOUR_BEARER_TOKEN`:
+
+```bash
+npx -y @pipeshub-ai/mcp start \
+  --server-url PIPESHUB_INSTANCE_URL \
+  --bearer-auth phpat_YOUR_TOKEN
+```
+
+A PAT works anywhere a session token or OAuth access token would — it's verified the same way, just with a longer lifetime and no OAuth flow required to obtain it.
+
+---
+
+## Managing Your Tokens
+
+The **Personal Access Tokens** page lists every active token you've created, with its name, scopes, creation date, expiry (`Never` shown as-is, not a literal date), and last-used time.
+
+### Revoking a Token
+
+Click the revoke icon next to a token and confirm. Revocation takes effect **immediately** — any request using that token (including one already in flight) is rejected on its next verification.
+
+<Warning>
+  Revocation is irreversible. Anything using the revoked token will need a new one.
+</Warning>
+
+---
+
+## Admin Visibility and Revocation
+
+Because a PAT can live for months or years, an org admin needs a way to see and revoke tokens they didn't create themselves — for example, when someone leaves the org or a laptop is compromised. This is available today via the API (no dedicated admin UI page yet):
+
+<CodeGroup>
+```bash List every active PAT in the org
+curl -X GET "https://your-pipeshub-instance.com/api/v1/personal-access-tokens/admin?page=1&limit=100" \
+  -H "Authorization: Bearer YOUR_SESSION_TOKEN"
+```
+
+```bash Revoke any user's token by id
+curl -X DELETE https://your-pipeshub-instance.com/api/v1/personal-access-tokens/admin/TOKEN_ID \
+  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"reason": "departed employee"}'
+```
+</CodeGroup>
+
+Both endpoints require organization-admin privileges and return `400` for non-admins. The list is paginated (`page`, `limit`, up to 100 per page) and includes each token's owner — including tokens whose owner has since been removed from the org, which still appear so they can be cleaned up.
+
+<Note>
+  A deleted user's own personal access tokens stop authenticating automatically — this admin flow is for auditing and proactive cleanup, not something you need to remember to do on every offboarding.
+</Note>
+
+---
+
+## API Endpoints Reference
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/v1/personal-access-tokens` | `POST` | Create a new personal access token |
+| `/api/v1/personal-access-tokens` | `GET` | List your own active tokens |
+| `/api/v1/personal-access-tokens/{tokenId}` | `DELETE` | Revoke one of your own tokens |
+| `/api/v1/personal-access-tokens/scopes` | `GET` | List the scopes available to grant, grouped by category |
+| `/api/v1/personal-access-tokens/admin` | `GET` | **Admin only.** List every active token in the org, paginated |
+| `/api/v1/personal-access-tokens/admin/{tokenId}` | `DELETE` | **Admin only.** Revoke any user's token by id |
+
+---
+
+## Security Notes
+
+<CardGroup cols={2}>
+
+<Card title="One-time display" icon="eye-slash">
+  The raw token is shown only at creation time. Only its hash is stored — PipesHub can't show it to you again if you lose it.
+</Card>
+
+<Card title="Scanner-friendly prefix" icon="magnifying-glass">
+  The `phpat_` prefix makes tokens easy to grep for in logs and files, and to catch with secret-scanning tools before they're committed somewhere they shouldn't be.
+</Card>
+
+<Card title="Short default expiry" icon="clock">
+  New tokens default to 30 days. Choose `Never` deliberately, not by default.
+</Card>
+
+<Card title="Immediate revocation" icon="ban">
+  Revoking a token — by you or an admin — takes effect on the token's next use, not after some delay.
+</Card>
+
+</CardGroup>
+
+---
+
+## FAQ
+
+<AccordionGroup>
+
+<Accordion title="What scopes can a personal access token have?">
+By default, a PAT gets your instance's full configured `MCP_SCOPES` set — the same scopes exposed to MCP clients (see [Customizing Default Scopes](/mcp/overview#customizing-default-scopes)). You can select a narrower set at creation time via the scope picker.
+</Accordion>
+
+<Accordion title="How is this different from a session token?">
+A session token is issued when you log in and expires after a short, fixed window (24 hours) — it's meant for browser sessions, not long-running integrations. A PAT is created deliberately, can live far longer, and can be revoked independently without logging you out everywhere else.
+</Accordion>
+
+<Accordion title="Can I see other users' personal access tokens?">
+No, unless you're an org admin. Regular users can only see and revoke tokens they created themselves. Admins can list and revoke any user's token via the [admin API](#admin-visibility-and-revocation) for incident response.
+</Accordion>
+
+<Accordion title="What happens to my tokens if I'm removed from the org?">
+They stop authenticating immediately — PipesHub rejects a personal access token whose owning user has been deleted, the same way it would reject an expired one.
+</Accordion>
+
+<Accordion title="Is there a limit on how many tokens I can create?">
+There's no fixed limit on creation, but the list view shows up to 100 of your most recent active tokens.
+</Accordion>
+
+</AccordionGroup>
diff --git a/docs.json b/docs.json
@@ -325,6 +325,7 @@
         "pages": [
           "developer/getting-started",
           "developer/oauth2",
+          "developer/personal-access-tokens",
           "developer/api-reference"
         ]
       },

diff --git a/mcp/local-server.mdx b/mcp/local-server.mdx
@@ -10,7 +10,11 @@ Instead of connecting to PipesHub's remote MCP endpoint, you can run the MCP ser
 
 - Node.js 20+ installed
 - A PipesHub instance URL
-- Authentication credentials: either a **Bearer token** (JWT) or **OAuth Client ID + Secret**
+- Authentication credentials: a **[Personal Access Token](/developer/personal-access-tokens)** (recommended — no OAuth app setup needed) or **OAuth Client ID + Secret**
+
+<Tip>
+  For the `--bearer-auth` flag used throughout this page, a [Personal Access Token](/developer/personal-access-tokens) is the easiest option: create one under **Developer Settings > Personal Access Tokens** and use it directly — no OAuth app, redirect URIs, or token exchange required.
+</Tip>
 
 ## Placeholders
 
@@ -19,7 +23,7 @@ Replace these in all configurations below:
 | Placeholder | Description | Example |
 |---|---|---|
 | `PIPESHUB_INSTANCE_URL` | Your PipesHub instance URL | `https://app.pipeshub.com` |
-| `YOUR_BEARER_TOKEN` | JWT Bearer token for authentication | `eyJhbGci...` |
+| `YOUR_BEARER_TOKEN` | [Personal access token](/developer/personal-access-tokens) (or any other Bearer JWT) | `phpat_eyJhbGci...` |
 | `YOUR_CLIENT_ID` | OAuth app client ID | `clid_abc123...` |
 | `YOUR_CLIENT_SECRET` | OAuth app client secret | `clsec_xyz789...` |
 

diff --git a/mcp/overview.mdx b/mcp/overview.mdx
@@ -17,7 +17,11 @@ This lets AI clients such as **Cursor**, **Claude Code**, **Gemini CLI**, **Clau
 ## Prerequisites
 
 - A running PipesHub instance (self-hosted or cloud)
-- An OAuth app created in PipesHub (see [Step 1](#step-1-create-an-oauth-app) below)
+- Either an OAuth app (see [Step 1](#step-1-create-an-oauth-app) below), **or** a [Personal Access Token](/developer/personal-access-tokens) — see the note below for which one to use
+
+<Note>
+  If you're connecting your own tooling and want it to act as you, the fastest path is a **[Personal Access Token](/developer/personal-access-tokens)**: create one under **Developer Settings > Personal Access Tokens**, then use it as `YOUR_BEARER_TOKEN` in any client config on this page or in [Local Server (Stdio)](/mcp/local-server) — no OAuth app or redirect URI setup required. Use an OAuth app instead when the integration is shared across users, or needs to run as an app rather than as a specific person.
+</Note>
 
 ## Step 1: Create an OAuth App
 
@@ -71,7 +75,7 @@ Replace these placeholders in all client configurations:
 | `PIPESHUB_INSTANCE_URL` | Your PipesHub instance URL | `https://app.pipeshub.com` |
 | `YOUR_CLIENT_ID` | OAuth app client ID | `clid_abc123...` |
 | `YOUR_CLIENT_SECRET` | OAuth app client secret | `clsec_xyz789...` |
-| `YOUR_BEARER_TOKEN` | JWT Bearer token (local stdio only) | `eyJhbGci...` |
+| `YOUR_BEARER_TOKEN` | [Personal access token](/developer/personal-access-tokens) (local stdio only) | `phpat_eyJhbGci...` |
 
 The remote MCP endpoint URL is: `PIPESHUB_INSTANCE_URL/mcp`