> For the complete documentation index, see [llms.txt](https://docs.goassay.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.goassay.ai/developers/zh/shang-jia-ni-de-api-ru-men/api-key-or-signature.md).

# API 密钥还是签名

选择 API 如何检查请求是否来自 Assay。

API 需要拒绝绕过 Assay 的调用。如果服务已经检查 API 密钥，可以从这种方式开始。如果还想检测被修改的请求和重复的签名调用，请使用 Assay 签名。

## 工作原理

使用 **API key** 时，Assay 会发送你在应用中保存的机密请求头。端点在处理请求前检查这些值。任何获得密钥的人都能使用它，因此请保密并使用 HTTPS。

使用 **Assay signature (recommended)** 时，端点使用 Assay 公钥验证 Ed25519 签名。无需保存共享 API 密钥。签名涵盖方法、主机、路径、查询参数、调用 ID，以及请求体存在时的 SHA-256 摘要。摘要是请求体原始字节的指纹。

| 选择                                | 端点必须执行的检查               | 保护及限制                                                      |
| --------------------------------- | ----------------------- | ---------------------------------------------------------- |
| **API key**                       | 要求机密请求头值匹配。             | 拒绝没有密钥的调用方。仅有密钥不会将调用与请求体绑定，也不能防止重放。                        |
| **Assay signature (recommended)** | 验证签名、请求体摘要、时间窗口和一次性随机数。 | 拒绝伪造或被修改的签名请求。随机数标识签名请求，让重放存储能够拒绝重复请求。只有共享该存储的实例之间才具备重放防护。 |
| **Both**                          | 两项检查都必须通过。              | 保留已有密钥检查，并增加签名验证。                                          |
| **Neither**                       | 不检查身份认证。                | 任何知道端点地址的人都能直接调用，无需通过 Assay 付款。                            |

在所有模式下，Assay 都会为普通提供方调用签名。即使改为签名模式，它仍会附加为目标源站保存的凭据请求头。选择模式不会在 API 中安装检查，也不会移除已保存的密钥。

## 设置 API 密钥

如果 API 已经拒绝无密钥调用，请采用此方式。在上架条目的 **Connect & test** 步骤中选择 **API key**，再选择 **Add headers**。[上架目录中的工具](https://docs.goassay.ai/list-your-api/zh/list-a-catalogue-tool)展示了每个界面。对你的 API 来说，需要注意：

* 将密钥放入请求头，不要放在地址中。使用 bearer 令牌时，填写 `Authorization` 和完整值 `Bearer YOUR_KEY`。
* 请求头按上架条目的源站保存：源站由地址的协议、主机和端口组成。不同的源站需要单独一组请求头。
* 值会加密保存，之后不再完整显示。保存会替换整组请求头，因此请包含 API 需要的所有请求头。

## 确认是否成功

正常调用应通过。测试器还会尝试不带密钥的调用。如果出现 **API key not enforced**，请修复：这表示端点接受了该调用。

## 改用签名验证

在 API 前部署网关，或在服务内部添加验证器。在 **Connect & test → Authentication** 中选择 **Assay signature (recommended)**；如果 API 还必须要求密钥，则选择 **Both**。没有默认选项。运行测试前先完成验证器安装；仅选择模式不会保护端点。

## 错误

| 现象                         | 解决方法                               |
| -------------------------- | ---------------------------------- |
| 测试要求提供 API 密钥请求头。          | 先保存连接，再为已保存的地址添加请求头。不同源站需要各自的请求头组。 |
| API 返回身份认证错误。              | 核对请求头名称和完整值是否与 API 读取的一致。          |
| **Signature not enforced** | 确保签名验证器覆盖 Assay 调用的路由，且不能被绕过。      |

## 延伸阅读

* 上架你的 API（可选）：[或者：发布你自己的 API](https://docs.goassay.ai/list-your-api/zh/publish-your-own-api)。

## 下一步

* [用 Cloudflare Worker 验证（无需代码）](/developers/zh/shang-jia-ni-de-api-ru-men/cloudflare-worker.md)。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.goassay.ai/developers/zh/shang-jia-ni-de-api-ru-men/api-key-or-signature.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.