Personal access tokens

A personal access token (PAT) is a bearer credential for a script, REST client, or integration. Anyone who obtains the secret can act with the token's permissions until it expires or is revoked, so create one only when an integration needs it.

For remote MCP clients that support OAuth 2.1 browser sign-in, prefer the Connect MCP authorization flow. Use a PAT for clients or automation that explicitly require a bearer token.

Tokens are narrower than accounts

A token does not reproduce your entire browser session. It has its own permission set and can be limited to particular workspaces.

Usable applies both of these boundaries:

1. your account must have sufficient access to the workspace;
2. the token must include the permission required for the operation.

Token creation is role-capped. You cannot create a token with permissions that exceed your effective workspace role. A Viewer or Subscriber cannot use token settings to obtain write access, and a Collaborator cannot create Owner-only authority.

Create a token

Open the token management surface exposed by the dashboard or use the authenticated token API when appropriate.

1. Choose Create token.
2. Give it a name that identifies one integration and environment.
3. Select global or workspace-specific access only where needed.
4. Enable the smallest permission set that supports the task.
5. Set an expiration date when the integration does not need permanent access.
6. Create the token.
7. Copy the secret immediately and store it in a secret manager.

The raw token is shown only when it is created. Usable stores token metadata for later management, not a reusable display of the secret.

A useful name is specific, such as docs-search-production or support-import-staging. Avoid vague names such as API token.

Permission families

The released token model includes these workspace-aware capability families:

Fragments

• fragments.read — list, search, and fetch fragment knowledge.
• fragments.create — create fragments.
• fragments.update — update existing fragments.
• fragments.delete — delete fragments where the role and endpoint allow it.

Semantic and filtered fragment search use fragments.read; a separate advanced-search permission is not required.

Workspace

Workspace capabilities include reading, creating, updating, and deleting workspaces, plus narrower management capabilities for members, invitations, fragment types, and public subscriptions. Current APIs and tools expose names such as workspace.read, workspace.create, workspace.update, workspace.delete, workspace.manage_members, workspace.manage_invitations, workspace.manage_fragment_types, and workspace.subscribe.

Not every role can select every capability. For example, Collaborators may manage invitations, while workspace deletion remains Owner-only.

Account-related capabilities

The token model also includes narrowly scoped notification and profile read/update capabilities where the current token UI or integration exposes them.

Use the permission descriptions shown by the current dashboard or API reference as the final source when creating a token; tool families can evolve independently.

Global and workspace-specific scope

A global permission applies across the workspaces your account can access and where your role supports that operation. A workspace-specific permission applies only to the selected workspace.

Prefer workspace-specific scope for most integrations. Use global scope only when a maintained integration intentionally needs to operate across all eligible workspaces.

A token can carry different permissions for different workspaces. For example, it can read two workspaces but create fragments in only one. Search without an explicit workspace is limited to workspaces for which the token has fragments.read.

Global permission never overrides your underlying membership. If your account loses access to a workspace, the token should not retain it merely because the token was once broader.

Use a token

Send the token through the standard bearer header over HTTPS:

Authorization: Bearer <personal-access-token>

Keep the value in a secret manager or protected environment variable. Do not place it in:

• fragment content or frontmatter;
• source code or committed .env files;
• issue trackers, chat messages, screenshots, or logs;
• browser-side code delivered to users;
• command examples that will be published.

Use placeholders in documentation and support requests.

Review and update tokens

The token management API supports listing tokens, reading metadata, updating a token, viewing usage analytics, and revoking it. Review active tokens periodically:

• Is the named integration still running?
• Has the token been used recently?
• Are its workspaces and permissions still necessary?
• Is the expiration appropriate?
• Does the owner still have the required workspace role?

Reduce permissions when a workflow becomes narrower. If a secret may have been exposed, do not rely on editing metadata alone—revoke it and create a replacement.

Rotate or revoke

To rotate a token safely:

1. Create a replacement with the same or narrower required scope.
2. Store the new secret in the integration's secret manager.
3. deploy or restart the integration and verify a low-risk operation;
4. revoke the old token;
5. confirm the old credential no longer works.

Revoke a token immediately when it is exposed, its integration is retired, its owner changes responsibilities, or its scope can no longer be justified.

Error handling

• 401 Unauthorized usually means the bearer credential is missing, malformed, expired, or revoked.
• 403 Forbidden means authentication succeeded but the token permission or underlying workspace role does not allow the operation.
• 404 Not Found can mean the resource does not exist or is hidden because the credential cannot access it.

When a token works in one workspace but not another, compare its workspace-specific permissions with the creator's current role in both workspaces.

Security checklist

• One token per integration and environment.
• Least-privileged, workspace-specific permissions by default.
• Expiration for temporary or replaceable automation.
• Secret-manager storage and HTTPS transport.
• No tokens in public or shared knowledge.
• Regular usage and scope review.
• Immediate revocation after suspected exposure.
• Verify replacement credentials before revoking during planned rotation.

Related pages

• Accounts and sign-in
• Workspace roles and permissions
• Search and retrieval
• Frontmatter and metadata