Copy

接入方首先需要确定是系统集成、个人测试，还是由最终用户主动授权。系统集成统一推荐团队版：不需要最终用户隔离时使用团队 Owner 临时凭证，需要平台隔离时使用虚拟成员临时凭证。用户 API Key 只推荐个人测试和临时调试。当前集成权益限制较小，系统集成现阶段仅用于开发和预发联调。正式生产上线需等待“集成版”权益套餐上线。团队版是系统集成的账号基础，但不等同于已经开通正式集成版权益。团队 AK/SK 暂未开放自助创建，未来随“集成版”套餐提供。当前需要联系秒悟团队创建测试凭证，并提供一个团队版账号用于绑定凭证和承载席位、项目及调用权益。

三种模式对比

对比项	团队系统集成（推荐）	用户 API Key（仅限个人测试）	OAuth 授权
典型场景	企业系统集成、单大账号、多租户 SaaS	个人测试、临时调试、个人 CLI	第三方产品代 Meoo 用户操作
长期凭证	团队 AK/SK	`meoo_ak_` API Key	Client Secret + Refresh Token
业务凭证	Owner 或虚拟成员短期 Bearer Token	同一个 API Key	OAuth Access Token
最终用户身份	Owner 模式无隔离；虚拟成员模式使用稳定 `member_id`	无，均为 API Key 创建者	Client 内稳定 `openid`
账号关联	Owner 模式无需用户映射；虚拟成员模式保存 `external_user_id → member_id`	无用户映射	`external_user_id → openid`
隔离责任	Owner 模式由接入方隔离；虚拟成员模式由 Meoo 按成员、项目隔离	仅适合用户自己的数据	Meoo 按授权用户、租户、项目隔离
用户交互	无	无	需要浏览器登录、同意授权
推荐账号	团队版；系统集成唯一推荐	个人账号即可；不推荐系统集成	由授权用户账号版本决定

模式一：团队系统集成（推荐）

接入方通过一个团队大账号接入。根据是否需要平台帮助隔离最终用户，选择 Owner 模式或虚拟账号模式；两者使用同一组团队 AK/SK 和成员 Token 接口。

Owner 大账号模式

不需要平台区分最终用户时，查询团队成员列表中 role=owner 的 Owner member_id，再为该成员签发短期 Token。后续项目、生成和发布均归属于团队 Owner，接入方自行保存业务对象与 project_id 的映射并负责最终用户授权。

虚拟账号隔离模式

需要 Meoo 识别接入方最终用户时，为每个外部用户创建团队托管成员。虚拟账号不需要真实手机号、邮箱或登录过程。

秒悟团队为接入方团队账号创建测试 AK/SK
        ↓ HMAC，仅可信服务端
选择已有 Owner，或按 external_user_id 创建/查找虚拟账号
        ↓ 接入方保存 external_user_id → member_id
为 member_id 签发 5～15 分钟 Token
        ↓ Bearer
调用项目、Agent、云能力和 Release API

Owner 和虚拟成员都使用 Meoo 持久化的随机 member_id；不要用 user_id + tenant_id 自行拼接。
团队 AK/SK 只能调用 /open/v1/team/members/**，不能直接调用业务 API。
成员 Token 无 Refresh Token；到期后由可信服务端使用 AK/SK 重新签发。
冻结成员或撤销团队凭证后，已有成员 Token 立即失效。
Owner 模式不提供最终用户隔离；所有调用共享 Owner 身份。
虚拟成员模式提供成员级资源归属、权限和审计隔离，但接入方仍须校验自身用户对业务对象的访问权。

团队版账号通常拥有更适合联调的额度和团队权益，因此现阶段优先推荐团队版。正式生产规模和服务保障仍以集成版权益套餐为准。HMAC 签名、幂等创建、成员生命周期和 Token 示例见团队系统集成指南。

模式二：用户 API Key（仅限个人测试）

适用于个人测试、临时调试和用户自己的 CLI。用户在前端“设置 → API 密钥”创建 meoo_ak_，选择最小 Scope，并保存在本人的可信环境：

Authorization: Bearer meoo_ak_xxx

API Key 代表创建它的主账号，不能通过请求参数切换用户。
所有项目、生成和发布均归属于该账号；接入方保存业务对象与 project_id 的映射并完成用户授权。
API Key 不能交给普通最终用户；若要交给执行器，只签发范围更小的项目级 Key。
API Key 无 Refresh；到期或撤销后创建新 Key。

该模式虽然接入简单，但不推荐用于系统集成，也不能作为绕过团队系统集成和集成版权益套餐的方式。系统集成即使只需要一个大账号，也应选择模式一并为团队 Owner 签发短期 Token；需要最终用户隔离时则使用虚拟成员 Token。

模式三：OAuth 授权

适用于第三方产品让已有 Meoo 用户登录并明确授权。请联系 Meoo 创建 Web/服务端应用，登记精确回调地址、允许账号版本和 Scope，获取 client_id 与 Client Secret。

Authorization Code + PKCE S256

GET {MEOO_BASE_URL}/oauth/authorize
  ?client_id=...
  &redirect_uri=...
  &response_type=code
  &scope=project.read%20project.write
  &state=...
  &code_challenge=...
  &code_challenge_method=S256

授权页必须在顶层浏览器窗口打开。state 和 code_verifier 逐次生成并在服务端校验；Authorization Code 一次有效，有效期 5 分钟。

curl --request POST \
  --url "${MEOO_BASE_URL}/oauth/token" \
  --user "${CLIENT_ID}:${CLIENT_SECRET}" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "code=${AUTHORIZATION_CODE}" \
  --data-urlencode "redirect_uri=${REDIRECT_URI}" \
  --data-urlencode "code_verifier=${CODE_VERIFIER}"

响应包含 1 小时 Access Token、30 天 Refresh Token、实际 Scope 和 openid。openid 只在当前 Client 内稳定，用于账号关联，不作为资源 API 参数。 Refresh Token 每次使用都会轮换，接入方必须原子保存新值；旧 Token 重放会吊销整个 Token Family。可通过 POST /oauth/revoke 主动吊销。

Scope 选择

能力	最小常用 Scope
创建、读取项目	`project.write`、`project.read`
AI 生成与进度	`agent.run`、`agent.read`
静态或生成结果发布	`release.write`、`release.read`
查询云服务	对应 `cloud.*.read`
修改数据库或 Secret	`cloud.database.write`、`cloud.secret.write`
上传私有 Skill	`skill.write`
导出项目当前源码	`source.read`

完整 Scope、可分配范围和接口对应关系见 API 目录。无论哪种模式，都只申请本次流程所需的最小权限。

凭证安全统一要求

API Key、团队 AK/SK、Client Secret、Refresh Token 只能保存在可信服务端。
Access Token 和成员短期 Token 也不应写入 URL、日志、前端持久存储或构建产物。
测试与生产使用不同凭证；轮换时允许短暂双凭证并行，再撤销旧凭证。
收到 401 时重新获取或轮换凭证；收到 403 时检查身份、租户、资源归属和 Scope，不要盲目重试。

​三种模式对比

​模式一：团队系统集成（推荐）

​Owner 大账号模式

​虚拟账号隔离模式

​模式二：用户 API Key（仅限个人测试）

​模式三：OAuth 授权

​Authorization Code + PKCE S256

​Scope 选择

​凭证安全统一要求