REST API：身份验证和使用

Last updated on Jun 24, 2026 01:46

PolyCMS 提供开箱即用的全面 RESTful API，允许您构建无头前端、移动应用程序或与第三方工具（如 Zapier、CRM 或 ERP 系统）集成。

API 位于“/api/v1”前缀处。

认证系统

PolyCMS 利用 Laravel Sanctum 来管理 API 身份验证。根据您的用例，它支持两种主要方法：

SPA 身份验证（Cookie）： 由内置 Vue 3 管理面板使用。它依赖于会话 cookie 和 CSRF 保护。

API 令牌身份验证： 用于外部应用程序、移动应用程序和“沙箱远程”模块。此方法使用不记名令牌。

本指南重点介绍外部集成的 API 令牌身份验证。

graph TD Client[客户端发送 HTTP 请求] --> HeaderCheck{是否包含 Authorization 请求头？} HeaderCheck -->|否| Unauth[返回 401 未授权错误] HeaderCheck -->|是| Extract[提取 Bearer 令牌] Extract --> QueryDB[查询数据库中的个人访问令牌] QueryDB --> TokenCheck{令牌存在且未过期？} TokenCheck -->|否| Unauth TokenCheck -->|是| ResolveUser[解析已验证的用户] ResolveUser --> PermissionCheck[检查权限和范围] PermissionCheck --> AuthCheck{是否已授权？} AuthCheck -->|否| Forbidden[返回 403 禁止访问错误] AuthCheck -->|是| Process[处理端点逻辑] Process --> SuccessResponse[返回 JSON 响应]

生成个人访问令牌 (PAT)

要访问受保护的端点，您必须生成令牌。

登录 PolyCMS 管理面板。

导航至 设置 > API 令牌（或单击您的用户个人资料）。

单击创建新令牌。

为令牌指定一个可识别的名称（例如“移动应用程序”或“Zapier 集成”）。

关键步骤： 您只会看到纯文本令牌一次。立即复制并将其存储在安全的密码管理器中。

发出 API 请求

获得令牌后，您必须将其包含在向 PolyCMS API 发出的每个 HTTP 请求的“授权”标头中。

示例：获取当前用户 (cURL)

curl -X GET https://polycms.org/api/v1/user \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_PLAIN_TEXT_TOKEN_HERE"

示例：创建帖子 (JavaScript/Fetch)

const response = await fetch('https://polycms.org/api/v1/posts', {
  method: 'POST',
  headers: {
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_PLAIN_TEXT_TOKEN_HERE'
  },
  body: JSON.stringify({
    title: 'Hello via API',
    slug: 'hello-via-api',
    content_raw: '{"blocks":[{"type":"paragraph","data":{"text":"Created via REST!"}}]}',
    status: 'draft'
  })
});

const data = await response.json();
console.log(data);

安全最佳实践

仅限 HTTPS： 始终通过安全的“https://”连接发出 API 请求。通过 HTTP 发送承载令牌会使您的系统容易被拦截。

令牌撤销： 如果您怀疑令牌已被泄露，请立即在管理面板中的 设置 > API 令牌 下撤销它。

权限： 目前，PAT 继承创建它们的用户的确切权限。确保使用仅具有任务所需权限的帐户生成令牌（例如，不要使用管理员帐户进行只读集成）。