Personal Access Tokens

Personal Access Tokens (PATs) let you authenticate API and MCP requests as yourself, with your own permissions and Organizational Unit access. Unlike service account credentials (which are shared and org-scoped), a PAT is tied to your user account — every request made with it acts as you.

When to Use This

• MCP Server authentication: The recommended way to connect the kenbun MCP Server to AI assistants. Your assistant inherits your exact permissions.
• Personal scripts and automation: Build scripts that run with your access without creating a shared service credential.
• Temporary integrations: Create tokens with an expiry date for short-lived use cases.
• Developer testing: Test API calls against your own account data without sharing credentials.

Understanding PATs vs. Service Accounts

	Personal Access Token	Service Account (API Secret)
Tied to	Your user account	The Organizational Unit
Permissions	Your role and OU access	All OU-level permissions
Best for	Personal scripts, MCP, developer tools	Production pipelines, shared systems
Where to create	Settings > Integrations > Personal Tokens	Settings > Integrations > Service Accounts

---

POST /settings/tokens

Create a new Personal Access Token. The full token value is returned once in this response — store it securely, as it cannot be retrieved again.

When to Use This

Use this endpoint when you need to generate a PAT programmatically, such as during onboarding automation or when provisioning access for a new tool.

Request Body

Field	Type	Required	Description
name	string	Yes	A descriptive label for this token (1–100 characters). Helps identify the token later.
expires_at	string	No	Expiry date and time in RFC 3339 format (e.g., "2026-12-31T23:59:59Z"). If omitted, the token does not expire.

Example Request Body:

{
  "name": "MCP Server - Laptop",
  "expires_at": "2027-01-01T00:00:00Z"
}

Response

Status: 201 Created

Field	Type	Description
id	string	Unique token identifier. Use this to revoke the token later.
name	string	The label you provided.
token	string	The full token value (begins with kbn_pat_). Shown only once — copy it now.
token_prefix	string	A short prefix used to identify the token in lists without exposing the full value.
created_at	string	When the token was created (ISO 8601).
expires_at	string or null	When the token expires, or null if it does not expire.

Example Response:

{
  "id": "pat_abc123",
  "name": "MCP Server - Laptop",
  "token": "kbn_pat_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "token_prefix": "kbn_pat_a1b2c3d4",
  "created_at": "2026-03-28T10:00:00Z",
  "expires_at": "2027-01-01T00:00:00Z"
}

Example

curl -X POST "https://api.kenbun.io/settings/tokens" \
  -H "Authorization: Bearer <your-session-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "MCP Server - Laptop",
    "expires_at": "2027-01-01T00:00:00Z"
  }'

Common Errors

Status	Meaning	Solution
400	Invalid request	Check that name is 1–100 characters and expires_at is a valid future RFC 3339 timestamp
401	Not authenticated	Log in to kenbun before creating a token
409	Token limit reached	Revoke unused tokens before creating new ones

---

GET /settings/tokens

List all Personal Access Tokens associated with your account. Token values are never included in this response — only metadata for managing your tokens.

Request

No query parameters required.

Response

Status: 200 OK

Returns an array of token objects.

Field	Type	Description
id	string	Unique token identifier
name	string	Descriptive label for the token
token_prefix	string	Short prefix to help identify which token this is
created_at	string	When the token was created
last_used_at	string or null	When the token was last used to make a request
expires_at	string or null	When the token expires, or null if it does not expire
revoked_at	string or null	When the token was revoked, or null if it is still active

Example Response:

[
  {
    "id": "pat_abc123",
    "name": "MCP Server - Laptop",
    "token_prefix": "kbn_pat_a1b2c3d4",
    "created_at": "2026-03-28T10:00:00Z",
    "last_used_at": "2026-03-28T14:22:00Z",
    "expires_at": "2027-01-01T00:00:00Z",
    "revoked_at": null
  },
  {
    "id": "pat_def456",
    "name": "CI Pipeline",
    "token_prefix": "kbn_pat_d4e5f6a1",
    "created_at": "2026-02-01T09:00:00Z",
    "last_used_at": null,
    "expires_at": null,
    "revoked_at": "2026-03-01T12:00:00Z"
  }
]

Example

curl -X GET "https://api.kenbun.io/settings/tokens" \
  -H "Authorization: Bearer <your-session-token>"

Common Errors

Status	Meaning	Solution
401	Not authenticated	Log in to kenbun before listing tokens

---

DELETE /settings/tokens/{id}

Revoke a Personal Access Token. Once revoked, any system using that token will immediately lose access. This action cannot be undone — you would need to create a new token.

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The token ID returned when the token was created, or from GET /settings/tokens

Response

Status: 204 No Content

No response body is returned on success.

Example

curl -X DELETE "https://api.kenbun.io/settings/tokens/pat_abc123" \
  -H "Authorization: Bearer <your-session-token>"

Common Errors

Status	Meaning	Solution
401	Not authenticated	Log in to kenbun before revoking a token
404	Token not found	Verify the token ID; you can only revoke your own tokens

---

Managing Tokens in the UI

You can create, view, and revoke tokens without using the API:

1. Go to Settings → Integrations → Personal Tokens
2. Click Create Token
3. Enter a name and optional expiry date
4. Copy the token value — it is shown only once
5. To revoke a token, click the delete icon next to it in the list

Security Best Practices

• Treat your PAT like a password. Anyone who has it can make API calls as you.
• Use descriptive names. "MCP Server - Work Laptop" is more useful than "my token".
• Set expiry dates. For temporary access or one-off scripts, set an expiry so the token becomes inactive automatically.
• Revoke tokens you no longer use. Check the Last Used column in Settings to find stale tokens.
• Never share your PAT. If you need shared access, use a Service Account credential instead.
• Store tokens in environment variables, not in code or config files committed to version control.

Related

• Service Account Credentials — Shared credentials for production pipelines
• Integrations Guide — Connecting the kenbun MCP Server using a PAT
• API Routes Overview — Authentication options for the kenbun API