# 鉴权与 AppKey 安全使用

区分 API AppKey 与 MCP OAuth，把凭据留在服务端，并排查权限和凭据错误。

## 核心步骤

- 取得目标产品对应的 AppKey。
- 优先通过请求头从后端发送凭据。
- 核对权限与错误类型，日志中移除凭据。

## 开始前准备

适合正在配置后端凭据或排查鉴权问题的开发者。先登录 [开发者中心](https://www.gugudata.com/portal/)，确认目标产品已开通，再到 APP KEY 管理页面复制该产品对应的 AppKey。准备一个能够安全保存环境变量的服务端运行环境。

## 先区分两种接入方式

直接调用 API 使用产品 AppKey；Remote MCP 由客户端发起 OAuth 账号授权。不要把 AppKey 填入 MCP OAuth 页面，也不要将 OAuth 访问令牌当作所有 API 的通用 AppKey。MCP 操作步骤见 [接入总览](https://www.gugudata.com/developers/mcp)。

## API 凭据如何传递

公开 API 支持下列鉴权入口。新接入优先选择请求头，既有 Query 调用保持兼容。一次请求只采用一种明确的方式，避免不同位置传入不同凭据。

| 方式 | 示例 | 注意事项 |
| --- | --- | --- |
| 推荐请求头 | `X-GUGUDATA-APPKEY: YOUR_APPKEY` | 适合后端服务与脚本 |
| 兼容请求头 | `X-API-Key: YOUR_APPKEY` | 与客户端已有配置保持一致 |
| Bearer | `Authorization: Bearer YOUR_APPKEY` | 此处是 API AppKey，不是 MCP OAuth 令牌 |
| Query | `?appkey=YOUR_APPKEY` | 不要把含凭据的 URL 存入截图、日志或分享链接 |

```bash
curl --get 'https://api.gugudata.com/weather/weatherinfo' \
  --header "X-GUGUDATA-APPKEY: ${GUGUDATA_APPKEY}" \
  --data-urlencode 'location=苏州' --data-urlencode 'days=1'
```

## 推荐调用链路

浏览器或移动客户端请求你自己的后端，后端读取运行环境中的凭据、验证业务请求，再调用 GuGuData。向前端返回必要结果，避免透传完整上游响应和内部凭据。

::: warning
构建时注入到前端 JavaScript 的环境变量并不是秘密。即使变量名含有 SECRET，打包后仍可能被用户读取。不要在前端代码、公开仓库、工单附件或 AI 对话中放入真实 AppKey。
:::

## 权限错误和凭据错误不同

凭据格式正确，不代表该产品权限有效。遇到失败时依次确认：当前 AppKey 是否属于目标产品、订单是否有效、额度是否足够、请求是否超过约定频率。以该接口错误码说明为准，不根据某一个数字推断所有 API 的错误类型。

普通 API 的价格、周期和可用能力由订单决定。不要把“成功登录网站”“MCP 连接成功”或“Demo 能运行”等同于正式 API 权限已经开通。

## 日志与凭据泄露后的处理

保留接口标识、脱敏参数摘要、耗时、HTTP 状态和业务状态，过滤 AppKey、Authorization、Cookie 及包含这些信息的完整 URL。不同系统的日志访问应有明确权限。

发现泄露时先停止公开传播并移除暴露入口，核查调用记录，然后通过 [开发者中心](https://www.gugudata.com/portal/) 或 [官方支持](https://www.gugudata.com/contact) 处理凭据更换与异常调用。AppKey 是否支持自助更新或单独管理，以开发者中心的实际功能为准。

## 完成后检查

用一次最小请求确认目标产品返回预期业务状态，并检查浏览器网络面板、前端产物和日志中没有真实凭据。权限仍不匹配时，继续按 [错误与重试指南](https://www.gugudata.com/developers/errors-and-retries) 分类排查，避免反复更换参数盲试。

AppKey 列表的查找、复制与状态核对见 [AppKey 与接口权限管理](https://www.gugudata.com/developers/portal/appkeys)；通知邮箱、安全记录和下载密钥见 [账号设置与安全](https://www.gugudata.com/developers/portal/account-security)。