Strapi API 令牌（API Tokens）使用与配置指南

#

概述

#

API Tokens 为 REST 与 GraphQL 请求提供基于令牌的分级认证方式，无需暴露用户账号凭据。它们适用于给第三方应用、脚本或团队成员按需授权访问 API（尤其适合无需完整用户账户管理的场景）。更多 API 相关介绍见官方文档：https://docs.strapi.io/cms/api/content-api

要点速览：

• 支持 Read-only、Full access 与 Custom 三种类型的令牌。
• 推荐对公开访问使用只读令牌（Read-only），并为服务器端使用限定权限的令牌（Server token）。
• 长期令牌应定期轮换（rotate）并存放在安全的密钥管理系统中。
• 切勿在客户端代码中暴露管理员（admin）令牌。

安全建议

#

• 优先使用最小权限原则（least privilege）：只授予访问需要的权限。
• 对于公开接口使用只读令牌。
• 对长期有效的令牌使用轮换策略并监控最后使用时间（last used）。
• 将令牌存放在 Secrets Manager 或安全的环境变量中，而不是源代码或前端代码里。

管理面板配置（在 Admin 中）

#

路径：Settings > Global settings > API Tokens

管理面板的 API Tokens 界面会显示已创建的令牌表格（字段：名称、描述、创建时间、最近使用时间）。可在此执行：

• 编辑（Edit）：修改名称、描述、类型、有效期或重新生成（Regenerate）。
• 删除（Delete）。

Strapi 会为你预生成两个令牌：一个 Full access 和一个 Read-only。注意：如果没有配置加密密钥（encryption key），令牌只会在创建或重生成后“显示一次”。建议配置加密密钥以便长期查看。

创建新 API 令牌（步骤）

#

1. 点击 “Create new API Token”。
2. 在令牌编辑界面填写配置：

1. 若选择 Custom，可为每个内容类型展开并通过复选框设置具体权限（例如 find / findOne / create / update / delete 等）。
2. 点击 Save。界面顶部将显示新令牌并提供复制按钮。

令牌可见性（Viewable tokens）

#

• 如果在项目配置中设置了加密密钥（admin.secrets.encryptionKey），新建或重生成的令牌将始终可以在管理面板中查看。
• 如果没有设置加密密钥，令牌只会在创建或重生成之后显示一次，之后管理面板不可见（但仍然可用用于请求）。

重生成（Regenerating）API 令牌

#

1. 在令牌列表中点击该令牌的编辑按钮（Edit）。
2. 点击 Regenerate 按钮。
3. 在弹窗中确认 Regenerate。
4. 在界面顶部复制新的令牌值。

注意：重生成会让旧令牌失效，请确保在所有使用旧令牌的地方更新为新令牌。

代码级别配置

#

API token salt（盐）

#

新 API token 的生成基于一个 salt 值。Strapi 会自动生成一个 salt 并把它作为环境变量写入 .env：

• 环境变量名：API_TOKEN_SALT

你可以通过两种方式自定义这个 salt：

1. 在 /config/admin 配置里设置 apiToken.salt 的字符串值。
2. 在项目的 .env 文件中设置 API_TOKEN_SALT 环境变量。

警告：更改 salt 会导致所有现有 API 令牌失效。

令牌在管理面板中可见：encryptionKey

#

要让令牌在管理面板中长期可见（可解密），需要在 /config/admin 中配置 secrets.encryptionKey，并通过环境变量注入：

/config/admin.js

module.exports = ({ env }) => ({
  // 其它配置
  secrets: {
    encryptionKey: env('ENCRYPTION_KEY'),
  },
});

/config/admin.ts

export default ({ env }) => ({
  // 其它配置
  secrets: {
    encryptionKey: env('ENCRYPTION_KEY'),
  },
});

该密钥用于加密/解密令牌值。没有该密钥，令牌在创建后仍可用于身份验证，但不能在管理面板中再次查看（除非重生成）。新创建的 Strapi 项目通常会自动生成该密钥。

使用方式（REST / GraphQL 请求）

#

在向 Strapi 发起 REST API 或 GraphQL 请求时，将 API 令牌放在 HTTP 请求头 Authorization 中：

示例（curl）：

curl -H "Authorization: bearer YOUR_API_TOKEN" <https://your-strapi-instance/api/articles>

GraphQL 请求同样在请求头中携带：

curl -X POST <https://your-strapi-instance/graphql> \\
  -H "Content-Type: application/json" \\
  -H "Authorization: bearer YOUR_API_TOKEN" \\
  --data '{"query":"{ articles { id title } }"}'

注意：Read-only 类型令牌只能访问 find 和 findOne（即查询）操作，不能用于创建/更新/删除。

常见建议与最佳实践

#

• 使用最小权限：给令牌分配恰好所需的权限。
• 优先使用只读令牌用于公共数据读取。
• 长期令牌请使用轮换策略，并储存于安全的凭据管理服务（如 Vault、AWS Secrets Manager 等）。
• 配置 secrets.encryptionKey 以便在管理面板中长期查看并管理令牌。
• 避免在前端或公开仓库中暴露任何敏感令牌，尤其是带有管理权限的令牌。

参考与更多资源

#

• 官方文档（原文）：https://docs.strapi.io/cms/features/api-tokens
• APIs 介绍：https://docs.strapi.io/cms/api/content-api
• Strapi 社区：https://discord.strapi.io/

标签：api tokens, admin panel, authentication, users & permissions, features