认证与授权

接入方首先需要确定是系统集成、个人测试，还是由最终用户主动授权。系统集成统一推荐团队版：不需要最终用户隔离时使用团队 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，不要盲目重试。

接入流程

Agent 专题

API Reference

三种模式对比

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

Owner 大账号模式

虚拟账号隔离模式

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

模式三：OAuth 授权

Authorization Code + PKCE S256

Scope 选择

凭证安全统一要求

​三种模式对比

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

​Owner 大账号模式

​虚拟账号隔离模式

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

​模式三：OAuth 授权

​Authorization Code + PKCE S256

​Scope 选择

​凭证安全统一要求

三种模式对比

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

Owner 大账号模式

虚拟账号隔离模式

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

模式三：OAuth 授权

Authorization Code + PKCE S256

Scope 选择

凭证安全统一要求