API Key 策略

要与第三方 API 或服务集成，你可能需要生成 API 密钥，用于在 Payload 中标识特定用户。API 密钥是按用户生成的，类似于电子邮件和密码，旨在代表单个用户。

例如，如果你有一个第三方服务或外部应用需要对 Payload 执行受保护操作，首先你需要在 Payload 中创建一个用户，例如 dev@thirdparty.com。你的外部应用需要通过该用户进行身份验证，此时你有两个选择：

  1. 每次使用该用户登录并获取一个会过期的令牌用于请求。
  2. 为该用户生成一个不会过期的 API 密钥用于请求。

提示：

这种方式特别有用，因为你可以创建一个"用户"来反映与特定外部服务的集成，并仅分配该服务/集成所需的"角色"或特定访问权限。

从技术上讲，这两种选项都适用于第三方集成，但使用 API 密钥的第二种方案更简单，因为它减少了集成需要进行身份验证的工作量。

要在 collection 上启用 API 密钥，请将 useAPIKey 认证选项设置为 true。之后，Admin Panel 中会为 collection 中的每个文档显示一个新界面，允许你为 Collection 中的每个用户生成 API 密钥。

import type { CollectionConfig } from 'payload'

export const ThirdPartyAccess: CollectionConfig = {
  slug: 'third-party-access',
  auth: {
    useAPIKey: true, // highlight-line
  },
  fields: [],
}

用户 API 密钥在数据库中是加密存储的，这意味着即使你的数据库遭到入侵，你的 API 密钥也不会泄露。

重要提示： 如果你更改了 PAYLOAD_SECRET，你将需要重新生成 API 密钥。

密钥用于加密 API 密钥，因此如果你更改了密钥，现有的 API 密钥将不再有效。

HTTP 认证

要通过 API 密钥对 REST 或 GraphQL API 请求进行认证，需要设置 Authorization 请求头。该请求头区分大小写，格式为：启用 auth.useAPIKey 的 collection 的 slug，后接 " API-Key "，最后跟上已分配的 apiKey。Payload 的内置中间件会将用户文档赋值给 req.user，并使用正确的访问控制处理请求。通过这种方式，Payload 会将请求识别为与该 API 密钥关联的用户所发出的请求。

例如，使用 Fetch：

import Users from '../collections/Users'

const response = await fetch('http://localhost:3000/api/pages', {
  headers: {
    Authorization: `${Users.slug} API-Key ${YOUR_API_KEY}`,
  },
})

Payload 确保在所有认证策略中使用统一一致的访问控制。这使得你可以将现有的访问控制配置同时应用于 API 密钥和标准的邮箱/密码认证。这种一致性有助于对 API 密钥保持精细控制。

仅限 API 密钥认证

如果你希望将 API 密钥作为 collection 的唯一认证方式，可以通过在 collection 的 auth 属性中设置 disableLocalStrategy 为 true 来禁用默认的本地策略。这将禁用通过邮箱和密码进行认证的能力，仅允许通过 API 密钥进行认证。

import type { CollectionConfig } from 'payload'

export const ThirdPartyAccess: CollectionConfig = {
  slug: 'third-party-access',
  auth: {
    useAPIKey: true,
    disableLocalStrategy: true, // highlight-line
  },
}