获取与使用 API Key

获取密钥与授权

如果你在组织中有密钥管理权限（owner 或 admin），在 Portal 的「接入应用 → 应用密钥」中生成 Consumer API Key。没有这个权限时，向你的组织管理员申请，并通过安全渠道接收密钥。拿到 Key 后即可调用 API，不必先登录 Portal。

同时向组织管理员确认你的应用、环境、数据集、平台和字段授权。生成 Key 不等于获得全部数据访问权限；订阅范围需要单独配置。Collector Key 和内部 Admin Token 不能代替此处的 Consumer API Key。

配置调用环境

所有示例统一使用 WHALE_BASE_URL 和 WHALE_API_KEY。生产服务地址为 https://www.marsyoo.com；使用测试环境时，换成组织管理员提供给你的地址与测试 Key。

通过 Secret Manager 或受保护的环境变量注入密钥，也可在 Bash 中交互输入，避免将明文写入命令历史：

export WHALE_BASE_URL="${WHALE_BASE_URL:-https://www.marsyoo.com}"
read -r -s -p "Consumer API Key: " WHALE_API_KEY
printf '\n'
export WHALE_API_KEY

不要打印密钥或将它放入前端。配置后进入完成第一次查询验证调用。

请求鉴权

所有外部读取接口都使用应用 API Key：

Authorization: Bearer whale_consumer_xxx

API Key 属于接入应用，不属于个人账号，也不用于登录 Portal。服务端从 Key 解析应用身份，客户端不应提交或伪造 consumer_id。

密钥管理

• 每个部署环境和外部系统使用独立 Key，便于审计和吊销。
• Key 只在生成时完整显示一次，不要写入源码、镜像或前端页面。
• 使用 Secret Manager、Key Vault 或受控环境变量保存。
• 轮换时先生成新 Key，完成流量切换后再吊销旧 Key。
• 怀疑泄露时立即在 Portal 吊销，并联系 Whale 平台支持。

响应语义

不要把应用密钥放在 URL 查询参数中。日志中只允许记录 Key 前缀，不得记录完整值。