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

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

## 获取密钥

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

您可以同时持有多个密钥，这样就能在不中断服务的情况下轮换：先创建新密钥，把流量切换过去，再吊销旧密钥。

## 在每个请求中携带

```bash
curl -X POST https://gateway.apinoa.com/v1/aliexpress/search \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{ "query": "phone case" }'
```

```javascript
const response = await fetch("https://gateway.apinoa.com/v1/aliexpress/search", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": process.env.APINOA_API_KEY,
  },
  body: JSON.stringify({ query: "phone case" }),
});
```

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

密钥会消耗您的余额。请从后端调用 API，并把密钥存放在密钥管理服务或环境变量中——切勿放在浏览器、
移动应用或公开代码仓库里，否则任何人都能读取它并以您的余额发起调用。

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

## 验证失败时

| 状态 | 代码 | 含义 |
|------|------|------|
| 401 | `UNAUTHORIZED` | 缺少 `x-api-key` 请求头，或密钥无效、已被吊销 |
| 402 | `INSUFFICIENT_BALANCE` | 密钥有效，但余额不足以支付此次调用 |

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