API 令牌

¥API Tokens

Page summary:
API tokens provide scoped authentication for REST and GraphQL requests without exposing user credentials. This documentation explains token types, creation, expiration, and secure usage within the admin panel.

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

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

安全

优先使用只读令牌进行公共访问，将服务器令牌的范围限定在所需范围内，轮换长期有效的令牌，并将它们存储在密钥管理器中。切勿在客户端代码中暴露管理员令牌。

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

Plan

Free feature

Role and 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 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

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

¥Click on the Create new API Token button.

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

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

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

（可选）对于自定义令牌类型，通过单击内容类型名称并使用复选框启用或禁用权限来定义 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.
单击“保存”按钮。新的 API 令牌将显示在界面顶部，同时显示复制按钮。

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

可查看的令牌

如果你的 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

单击 API 令牌的编辑按钮。

¥Click on the API token's edit button.
单击“重新生成”按钮。

¥Click on the Regenerate button.
单击对话框中的“重新生成”按钮进行确认。

¥Click on the Regenerate button to confirm in the dialog.
复制界面顶部显示的新 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 文件中 apiToken.salt 的字符串值来实现

¥either by updating the string value for apiToken.salt in your /config/admin file
或者通过在项目的 .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.

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

¥Ensuring API tokens are visible in the admin panel

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

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

JavaScript
TypeScript

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

/config/admin.ts
export default ({ 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.

注意

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

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

配置​

管理面板设置​

创建新的 API 令牌​

重新生成 API 令牌​

基于代码的配置​

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

用法​

配置

管理面板设置

创建新的 API 令牌

重新生成 API 令牌

基于代码的配置

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

用法