Skip to main content

API 令牌

🌐 API Tokens

Page summary:

API 令牌为 REST 和 GraphQL 请求提供范围化身份验证，而无需暴露用户凭据。本指南解释了令牌类型、创建、过期以及在管理面板中的安全使用方法。

API 令牌允许用户对 REST 和 GraphQL API 查询进行身份验证（参见 API 介绍）。

🌐 API tokens allow users to authenticate REST and GraphQL API queries (see APIs introduction).

Security

公共访问偏向使用只读令牌，将服务器令牌的权限限制在仅所需范围内，定期更换长期有效的令牌，并将它们存储在秘密管理器中。切勿在客户端代码中暴露管理员令牌。

🌐 Prefer read‑only tokens for public access, scope server tokens to only what you need, rotate long‑lived tokens, and store them in a secrets manager. Never expose admin tokens in client‑side code.

IDENTITY CARD
计划

免费功能

角色与权限

最小“访问API令牌设置页面”在 角色 > 设置 - API令牌

激活

默认可用

环境

可在开发和生产环境中使用

API tokensAPI tokens

配置​

🌐 Configuration

API 令牌的大多数配置选项都可以在管理面板中使用，并且你的 Strapi 项目的代码可用于更改 API 令牌的生成方式。

🌐 Most configuration options for API tokens are available in the admin panel, and your Strapi project's code can be used to alter how API tokens are generated.

管理面板设置​

🌐 Admin panel settings

配置此功能的路径： 设置 > 全局设置 > API 令牌

API 令牌 界面显示一个表格，列出所有已创建的 API 令牌。更具体地，它显示每个 API 令牌的名称、描述、创建日期和最后使用日期。

🌐 The API Tokens interface displays a table listing all of the created API tokens. More specifically, it displays each API token's name, description, date of creation, and date of last use.

从那里，你可以：

🌐 From there, you have the possibility to:

  • 点击 以编辑 API 令牌的名称、描述、类型、有效期或重新生成令牌。
  • 点击 以删除API令牌。
Note

Strapi 会为你预生成 2 个 API 令牌，一个是完全访问令牌，另一个是只读令牌。由于令牌在未配置加密的情况下只能查看一次，你可能希望在设置加密密钥后重新生成它们，以便永久可见。

🌐 Strapi pre-generates 2 API tokens for you, a Full access one and a Read-only one. Since tokens can be only seen once without encryption configured, you may want to regenerate them after setting up an encryption key to make them permanently viewable.

创建新的 API 令牌​

🌐 Creating a new API token

  1. 点击 创建新的 API 令牌 按钮。
  2. 在 API 令牌编辑界面，配置新的 API 令牌： | 设置名称 | 说明 || -------- | ----------------------------------------------------------- || 名称 | 输入 API 令牌的名称。 || 描述 | （可选）为 API 令牌输入描述。 || 令牌有效期 | 选择令牌有效期：7 天，30 天，90 天 或 无限。 || 令牌类型 | 选择令牌类型：只读，完全访问 或 自定义。 |
  3. （可选）对于 Custom 令牌类型，通过点击内容类型名称并使用复选框启用或禁用权限，为你的 API 端点定义特定权限。
  4. 点击 保存 按钮。新的 API 令牌将显示在界面顶部，并带有一个复制按钮 。
Custom API tokenCustom API token
Viewable tokens

如果在你的 Strapi 项目中配置了加密密钥（admin.secrets.encryptionKey），新创建和重新生成的 API 令牌将可以随时在管理面板中查看。

🌐 If an encryption key is configured in your Strapi project (admin.secrets.encryptionKey), the newly created and regenerated API tokens will be viewable at any time in the admin panel.

如果未设置加密密钥，令牌将只能查看一次，即在创建或重新生成后立即查看。

🌐 If no encryption key is set, tokens will only be viewable once, immediately after creation or regeneration.

重新生成 API 令牌​

🌐 Regenerating an API token

  1. 单击 API 令牌的编辑按钮。
  2. 点击 重新生成 按钮。
  3. 点击 重新生成 按钮，在对话框中确认。
  4. 复制界面顶部显示的新 API 令牌。

基于代码的配置​

🌐 Code-based configuration

新的 API 令牌是使用盐生成的。该盐由 Strapi 自动生成，并作为 API_TOKEN_SALT 存储在环境变量（.env 文件）中。

🌐 New API tokens are generated using a salt. This salt is automatically generated by Strapi and stored in environment variables (the .env file) as API_TOKEN_SALT.

盐可以定制：

🌐 The salt can be customized:

Caution

更改盐会使所有现有的 API 令牌失效。

🌐 Changing the salt invalidates all the existing API tokens.

确保 API 令牌在管理面板中可见​

🌐 Ensuring API tokens are visible in the admin panel

要在管理面板中允许 API 令牌的持久可见性，必须在your /config/admin 文件的 secrets.encryptionKey 下提供加密密钥：

🌐 To allow persistent visibility of API tokens in the admin panel, an encryption key must be provided in your /config/admin file under secrets.encryptionKey:

/config/admin.js
module.exports = ({ env }) => ({
  // other config parameters
  secrets: {
    encryptionKey: env('ENCRYPTION_KEY'),
  }
});

此密钥用于加密和解密令牌值。没有此密钥，令牌仍然可以使用，但在初次显示后将无法查看。新的 Strapi 项目将自动生成此密钥。

🌐 This key is used to encrypt and decrypt token values. Without this key, tokens remain usable, but will not be viewable after initial display. New Strapi projects will have this key automatically generated.

使用​

🌐 Usage

使用 API 令牌可以以经过身份验证的用户身份在 REST API 或 GraphQL API 端点上执行请求。

🌐 Using API tokens allows executing a request on REST API or GraphQL API endpoints as an authenticated user.

API 令牌有助于授予人员或应用访问权限，而无需管理用户账户或更改用户和权限插件中的任何内容。

🌐 API tokens can be helpful to give access to people or applications without managing a user account or changing anything in the Users & Permissions plugin.

在向 Strapi 的 REST API 执行请求时，API 令牌应以以下语法添加到请求的 Authorization 头中：bearer your-api-token。

🌐 When performing a request to Strapi's REST API, the API token should be added to the request's Authorization header with the following syntax: bearer your-api-token.

Note

只读 API 令牌只能访问 find 和 findOne 功能。

🌐 Read-only API tokens can only access the find and findOne functions.