车库

BaaS 鉴权

读完本页应能接上：每个请求如何带项目身份，游客如何变成登录用户，以及支付写操作要遵守什么。

下游产品（心跳榜、上头短剧，或你自己的客户端）不传 project_id。服务端用 API Key 识别项目。

两张凭证

凭证放哪代表谁用途
API Key请求头 X-API-Key项目路由、配额、项目隔离
App JWTAuthorization: Bearer用户登录后的个人接口
仅 Key无用户 token匿名落地页、部分埋点等白名单

Key 在运营后台「API 密钥」签发、轮换、吊销。客户端不要把 Key 写进公开仓库。

API Key 格式与规则

格式：mpk_<project_code>_<32hex>（例：mpk_beatrank_a1b2c3d4…）。

  • 明文只在签发时返回一次；服务端只存 SHA-256 哈希。
  • 前缀 mpk_<project_code>_ 可展示 / 搜索，不足以还原完整 key。
  • 同一项目允许多把 active key（滚动替换）；数量有上限。

验证顺序：无头可走兼容路径 → 有头则查 active 哈希 → 校验项目未归档 → 限流 → 注入 project_id 进上下文。

典型时序

  1. 每个请求带 X-API-Key。
  2. POST /api/v1/auth/device-session 拿到游客会话（或账密 / 短信登录换用户 JWT）。
  3. 后续 /api/v1/app/me*、下单、解锁带 Bearer。
  4. 内容只读列表在登录前也可访问（仍要 Key）；服务端只返回 on_shelf。

通用约定

  • 错误码：大写下划线，如 INSUFFICIENT_BALANCE、UNLOCK_REQUIRED、SMS_RATE_LIMITED。
  • 幂等：支付类写操作强制 Idempotency-Key（UUID）；重复提交返回原单。埋点用 event_id 日内幂等。
  • 限流：按 API Key 配额；短信验证码约 60s 频控。
  • 金额：人民币用「分」（整数）；金币用整数。比率为空返回 null，客户端显示「—」，不要显示 0。
  • 支付成功：只认服务端订单 paid。渠道回调验签与幂等在服务端完成；客户端自报不算数。

接入清单

  1. 后台创建项目，签发 Key。
  2. 按 能力地图 接登录 → 内容 → 支付。
  3. 埋点走 POST /api/v1/events/batch，使用平台标准事件名。
  4. 心跳榜需要 Android 壳时，用 Capacitor 包同一套 H5，继续打同一套头与路径。上头短剧的 App 是独立 Flutter 工程，鉴权约定相同。

路径与字段以仓库 docs/openapi/baas-app-v1.yaml 为准，见 契约说明。