Tiptap 访问控制（预览版）

通常不可用

Tiptap Access Control 认证格式目前处于预览阶段，默认未启用。如需申请访问权限，请发送电子邮件至 humans@tiptap.dev。在启用之前，请继续使用安装指南中描述的 App ID + secret 流程——它仍然可以正常工作，且无需更改。

Tiptap Access Control 是一种新的认证格式，它使用单个带有明确权限的已签名 JWT，取代了 X-App-Id + 按服务划分的 secret。这两种格式并存：只有当 JWT 的 audience 声明为 "AI" 时，服务才会将请求路由到新路径，因此现有集成无需更改即可继续工作。

如何启用

发送电子邮件至 humans@tiptap.dev，并请求为你的 Tiptap Cloud 环境启用 Tiptap Access Control。我们会配置签名密钥，并在你的环境准备就绪后通知你。
生成 JWT，设置 aud: "AI"、将你的环境 id 作为 iss，并使用 permissions 数组列出该令牌被允许执行的操作（见下文）。
在 Authorization: Bearer <jwt> 请求头中发送 JWT。此路径不会读取 X-App-Id 请求头。

权限

操作	授权
`AI:Toolkit`	所有 Server AI Toolkit 端点（tools、workflows、execute-tool）
`Documents:Write`	对 Tiptap Cloud 文档的读取、写入和评论权限。使用 `experimental_documentOptions` 时需要此权限，以便 AI 服务器可以自动获取并保存文档。

Documents:Write 隐含读取和评论权限，因此对于 toolkit 工作流，你不需要单独的 Documents:Read 或 Documents:Comment 权限。

示例 token 载荷

用于仅限 toolkit 访问、且不集成文档服务器的 token：

{
  "iss": "env_abc123",
  "aud": ["AI"],
  "exp": 1777033105,
  "permissions": [{ "action": "AI:Toolkit", "resource": "*" }]
}

一个同样允许 toolkit 获取并保存 Tiptap Cloud 文档的 token：

{
  "iss": "env_abc123",
  "aud": ["AI", "Documents"],
  "exp": 1777033105,
  "permissions": [
    { "action": "AI:Toolkit", "resource": "*" },
    { "action": "Documents:Write", "resource": "my-document-id" }
  ]
}

错误响应

当 token 缺少所需权限时，服务会返回 403 Forbidden，并附带：

{
  "message": "Token is missing permission AI:Toolkit.",
  "code": "permission_denied"
}

如果环境的订阅根本不包含 Server AI Toolkit，则响应为 403，并带有 code: feature_not_available。

使用 Tiptap Access Control 配置授权

安装 JWT 签名库：

npm install jose

环境变量

配置以下环境变量：

# .env
TIPTAP_CLOUD_AI_API_URL=https://api.tiptap.dev
TIPTAP_ENVIRONMENT_ID=your-environment-hash-id
TIPTAP_PRIVATE_KEY=your-private-key-pem

TIPTAP_CLOUD_AI_API_URL：Server AI Toolkit API 的基础 URL。
TIPTAP_ENVIRONMENT_ID：你在 Tiptap 仪表板中的环境哈希 ID。签名 JWT 时用作 iss 声明。
TIPTAP_PRIVATE_KEY：你在 Tiptap 仪表板中的 ES256 私钥（PKCS#8 PEM）。用于在服务端签名 JWT。

创建 JWT token

此函数会生成一个用于通过 Server AI Toolkit API 进行认证的 JWT。当 Server AI Toolkit 需要通过 experimental_documentOptions 自动获取并保存 Tiptap Cloud 文档时，请传入 documentId。

// lib/server-ai-toolkit/create-jwt-token.ts
import { SignJWT, importPKCS8 } from 'jose'

type CreateJwtTokenOptions = {
  documentId?: string
}

/**
 * 生成一个用于通过 Server AI Toolkit API 进行认证的 JWT
 */
export async function createJwtToken(options: CreateJwtTokenOptions = {}): Promise<string> {
  const privateKey = await importPKCS8(process.env.TIPTAP_PRIVATE_KEY!, 'ES256')

  const permissions: { action: string; resource: string }[] = [
    { action: 'AI:Toolkit', resource: '*' },
  ]

  if (options.documentId) {
    permissions.push({ action: 'Documents:Write', resource: options.documentId })
  }

  return new SignJWT({ permissions })
    .setProtectedHeader({ alg: 'ES256' })
    .setIssuer(process.env.TIPTAP_ENVIRONMENT_ID!)
    .setAudience(options.documentId ? ['AI', 'Documents'] : ['AI'])
    .setIssuedAt()
    .setExpirationTime('30m')
    .sign(privateKey)
}

替代方案：直接提供文档

如果你在自己的存储中管理文档，而不是使用 Tiptap Cloud，请省略 documentId 选项，并在 API 请求中通过 document 字段直接传递文档。此时 token 只需要 AI:Toolkit 权限。

调用 API 端点

认证成功后，调用 Server AI Toolkit API 端点。生成 JWT 并设置 Authorization 请求头。

当使用 Tiptap Cloud 文档时，传入文档 ID 以包含 Documents:Write 权限。

const jwt = await createJwtToken({ documentId: 'my-document-id' })

const response = await fetch(`${apiBaseUrl}/v3/ai/toolkit/execute-tool`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${jwt}`,
  },
  body: JSON.stringify({
    toolName: 'tiptapEdit',
    input: toolCallInput,
    editorContext,
    experimental_documentOptions: {
      documentId,
    },
  }),
})

完整的 API 文档请参见 REST API 参考。

有关 Tiptap Access Control 的更多信息，请参见认证指南。

Previously安装

Next upAgents