> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meoo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 认证与授权

接入方首先需要确定是系统集成、个人测试，还是由最终用户主动授权。系统集成统一推荐团队版：不需要最终用户隔离时使用团队 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 识别接入方最终用户时，为每个外部用户创建团队托管成员。虚拟账号不需要真实手机号、邮箱或登录过程。

```text theme={null}
秒悟团队为接入方团队账号创建测试 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 示例见[团队系统集成指南](https://app.mintlify.com/alibaba-b47c397f/alibaba-b47c397f/~/8b2e4f11-3395-4dd1-b58e-2e6935dd1392)。

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

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

```text theme={null}
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

```text theme={null}
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 分钟。

```text theme={null}
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 目录](https://app.mintlify.com/alibaba-b47c397f/alibaba-b47c397f/~/3b133dc5-c1b4-420a-a368-c1733cdd88a7)。无论哪种模式，都只申请本次流程所需的最小权限。

## 凭证安全统一要求

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