认证与 API Key

开放 API 和 MCP 服务器只接受一种认证方式：在 HTTP 请求头里携带 API Key。没有 OAuth，也没有基于 Cookie 的登录态。

请求头格式

Authorization: Bearer gdev_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

每个请求带且只带一个 Authorization 头，scheme 写 Bearer（大小写不敏感），后跟一个空格和完整 Key。
API Key 以 gdev_ 开头，共 48 个字符。控制台列表里展示的是前 12 个字符（如 gdev_Ab3dEfG），用来区分不同的 Key。
Key 只能放在请求头里。放在 URL 查询参数或请求体里都不会被识别；请求体里出现 api_key 这类接口未定义的字段，会直接返回参数错误 1001。

在开发者控制台 → API Key 页创建。完整 Key 只在创建或重置成功时显示一次，服务端只保存它的摘要，事后无法再查看。遗失只能重置或新建。

创建、停用、重置、删除等操作见管理 API Key。

API Key 代表创建它的用户在其个人账户下调用接口：

一个 Key 能做的事与开放 API 一一对应：查询平台、提交任务、查询任务、列出任务。Key 不能用来管理 Key 本身，也不能访问 MaxAEO 产品里的品牌监控数据。

服务端在每个请求上重新校验 Key：Key 存在、处于启用状态、未过期，且所属用户和账户仍然有效。任一条件不满足，开放 API 都返回：

{
  "ret": 1030,
  "msg": "{\"zh\":\"API Key 无效、已停用或已过期\",\"en\":\"The API key is invalid, disabled or expired.\"}"
}

缺少 Authorization 头、格式不对、出现多个 Authorization 头时也返回 1030。出于安全考虑，1030 不区分具体原因，请按下面的顺序排查：

停用、删除 Key，或 Key 到期后：

用这个 Key 发起的新请求立即被拒绝（1030）。
已经提交、但还在本地排队（queued）没有派发出去的任务，派发时会失败，error_code 为 credential_invalid，不扣点数。
已经派发给平台执行的任务照常完成，结果仍可以用其他有效 Key 或在控制台查询。

只在服务端使用。 不要把 Key 写进网页前端、小程序、App 安装包、浏览器插件或公开的代码仓库；在服务端通过环境变量或密钥管理服务读取。
按环境、按项目分开创建。 例如「生产」「测试」「数据看板」各一个。单个 Key 泄露时，停用或重置它即可，不影响其他调用；控制台也能按 Key 查看用量。
为非长期用途设置有效期。 临时脚本、外包协作用的 Key 选 30 天或 90 天有效期，到期自动失效。
定期轮换，平滑替换。 用「重置 Key」生成新 Key，并给旧 Key 留出宽限期（1 小时、24 小时或 7 天），先把新 Key 部署上线，再让旧 Key 自然失效。
怀疑泄露时立即处理。 在控制台重置并选择「立即失效」，或直接停用；然后在调用日志里检查是否有异常调用。
不要在日志里打印完整 Key。 需要标识 Key 时，记录前 12 个字符即可。