API 令牌

¥API Tokens

API 令牌允许用户验证 REST 和 GraphQL API 查询（请参阅 API 介绍）。

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

功能的身份证

计划:免费功能。
角色和权限：角色 > 设置中的最低 "访问 API 令牌设置页面" - API 令牌。
激活:默认可用。
环境:在开发和生产环境中均可用。

¥ Plan: Free feature.
Role & permission: Minimum "Access the API tokens settings page" in Roles > Settings - API tokens.
Activation: Available by default.
Environment: Available in both Development & Production environment.

配置

¥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 令牌

¥Path to configure the feature: Settings > Global settings > API Tokens

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 令牌的名称、描述、类型、持续时间或 重新生成令牌。

  ¥click on the to edit an API token's name, description, type, duration or regenerate the token.

• 单击 以删除 API 令牌。

  ¥click on the to delete an API token.

注意

Strapi 为你预先生成 2 个 API 令牌，一个完全访问权限令牌和一个只读令牌。由于令牌在创建后只能看到一次，因此你必须在使用它们之前对其进行 regenerate。

¥Strapi pre-generates 2 API tokens for you, a Full access one and a Read-only one. Since tokens can be only seen once after creation, you have to regenerate them before using them.

创建新的 API 令牌

¥Creating a new API token

1. 单击创建新的 API 令牌按钮。

   ¥Click on the Create new API Token button.

2. 在 API token 版本界面中，配置新的 API token：

   ¥In the API token edition interface, configure the new API token:

   设置名称	指示
   名称	写入 API 令牌的名称。
   描述	（可选）编写 API 令牌的描述。
   令牌持续时间	选择令牌持续时间：7 天、30 天、90 天或无限制。
   令牌类型	选择令牌类型：只读、完全访问或自定义。

3. （可选）对于自定义令牌类型，通过单击内容类型名称并使用复选框启用或禁用权限来定义 API 端点的特定权限。

   ¥(optional) For the Custom token type, define specific permissions for your API endpoints by clicking on the content-type name and using checkboxes to enable or disable permissions.

4. 单击“保存”按钮。新的 API 令牌将显示在界面顶部，同时显示复制按钮 。

   ¥Click on the Save button. The new API token will be displayed at the top of the interface, along with a copy button .

提醒

出于安全原因，API 令牌仅在创建后立即显示。刷新页面或导航到管理面板中的其他位置时，新创建的 API 令牌将被隐藏，并且不会再次显示。

¥For security reasons, API tokens are only shown right after they have been created. When refreshing the page or navigating elsewhere in the admin panel, the newly created API token will be hidden and will not be displayed again.

重新生成 API 令牌

¥Regenerating an API token

1. 单击 API 令牌的编辑按钮。

   ¥Click on the API token's edit button.

2. 单击“重新生成”按钮。

   ¥Click on the Regenerate button.

3. 单击对话框中的“重新生成”按钮进行确认。

   ¥Click on the Regenerate button to confirm in the dialog.

4. 复制界面顶部显示的新 API 令牌。

   ¥Copy the new API token displayed at the top of the interface.

基于代码的配置

¥Code-based configuration

新的 API 令牌是使用 salt 生成的。此盐由 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:

• 通过更新 ./config/admin.js 中 apiToken.salt 的字符串值（参见 管理面板配置文档）

  ¥either by updating the string value for apiToken.salt in ./config/admin.js (see admin panel configuration documentation)

• 或者通过在项目的 .env 文件中创建 API_TOKEN_SALT 环境变量

  ¥or by creating an API_TOKEN_SALT environment variable in the .env file of the project

提醒

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

¥Changing the salt invalidates all the existing API tokens.

用法

¥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.

注意

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

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