鉴权与 AppKey 安全使用

开始前准备

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

先区分两种接入方式

直接调用 API 使用产品 AppKey；Remote MCP 由客户端发起 OAuth 账号授权。不要把 AppKey 填入 MCP OAuth 页面，也不要将 OAuth 访问令牌当作所有 API 的通用 AppKey。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 存入截图、日志或分享链接

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

推荐调用链路

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

权限错误和凭据错误不同

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

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

日志与凭据泄露后的处理

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

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

完成后检查

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

AppKey 列表的查找、复制与状态核对见 AppKey 与接口权限管理；通知邮箱、安全记录和下载密钥见 账号设置与安全。