---
title: "身份验证"
description: "每个请求都通过 x-api-key 请求头中的 API 密钥进行身份验证。"
---

> Every apinoa docs page as markdown: https://apinoa.com/llms.txt (all in one file: https://apinoa.com/llms-full.txt)

发往 `gateway.apinoa.com` 的每个请求都在 `x-api-key` 请求头中携带 API 密钥。没有其他身份验证方式，
没有密钥的请求一律不予处理。

## 获取密钥

在**控制台 > API 密钥**中创建密钥。完整密钥仅在创建时显示**一次**：请当场复制并妥善保存。如果丢失，
请创建新密钥并吊销旧密钥。

也可以不打开控制台，直接在终端中获取密钥。在项目目录下运行：

```bash
npx apinoa-mcp login
```

它会输出页面地址 `https://api.apinoa.com/oauth/device` 和一个 8 个字符的代码（如 `BCDF-GHJK`）；在交互式终端中，
页面会自动打开。在该页面登录 apinoa（没有账户可以新建），输入代码并批准。随后命令会把 `APINOA_API_KEY=<key>`
写入当前目录的 `.env`（用 `--out <path>` 可写入其他文件）。已有的 `APINOA_API_KEY` 行会被替换，文件其余内容保持不变；
如果 `.env` 未被 git 忽略，它会发出警告。完整密钥不会被打印出来。

以这种方式获得的密钥以 `apinoa_mcp_` 开头，90 天后过期，届时再次运行 `npx apinoa-mcp login` 即可。它同样显示在
**控制台 > API 密钥**中，可以像其他密钥一样吊销；每次以这种方式创建密钥时，我们都会发邮件通知您。每个账户最多保留五个
CLI 密钥：第六次登录会吊销最旧的一个，并告诉您是哪一个。通过这种方式或登录[托管版 MCP 服务器](/docs/sdks#托管版无需安装)
首次获得的密钥附带 **$0.10 评估额度**，每个账户仅限一次；已经领取过免费额度的账户不会再获得。

**只输入你刚刚在自己的终端中亲自发起的代码。** 任何发来代码让你输入的人，都是在索取你账户的访问权限。

你可以同时持有多个密钥，这样就能在不停机的情况下轮换密钥：创建新密钥，将流量迁移过去，然后吊销旧密钥。

## 每个请求都要发送

```bash tab="cURL"
curl "https://gateway.apinoa.com/v1/amazon/search?query=wool+socks" \
  -H "x-api-key: $APINOA_API_KEY"
```

```js tab="JavaScript"
const res = await fetch("https://gateway.apinoa.com/v1/amazon/search?query=wool+socks", {
  headers: { "x-api-key": process.env.APINOA_API_KEY },
});
```

```python tab="Python"
import os

import requests

res = requests.get(
    "https://gateway.apinoa.com/v1/amazon/search",
    params={"query": "wool socks"},
    headers={"x-api-key": os.environ["APINOA_API_KEY"]},
)
```

## 将密钥保存在服务器端

密钥会消耗你的余额。请从后端调用 API，并将密钥保存在密钥管理服务或环境变量中：绝不要放在浏览器、移动应用
或公开代码仓库中，否则任何人都能读取它并以你的名义产生调用费用。

如果密钥可能已泄露，请在**控制台 > API 密钥**中吊销它。吊销的密钥会立即失效。

## 身份验证失败时

| 状态码 | 代码 | 含义 |
|---|---|---|
| 401 | `UNAUTHORIZED` | 缺少 `x-api-key` 请求头，或密钥无效或已吊销。 |
| 402 | `INSUFFICIENT_BALANCE` | 密钥有效，但余额不足以支付本次调用。 |
| 403 | `ACCOUNT_SUSPENDED` | 账户已被停用；其下所有密钥都会被拒绝。请联系支持。 |

每次调用按[价格页面](/pricing)上的费率从余额中扣费。当余额不足以支付下一次调用时，API 返回 `402`，
重试无法解决：请在**控制台 > 余额**中充值。