> ## 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.

# 团队系统集成

团队系统集成适用于接入方以一个团队账号接入 Meoo。接入方持有团队长期 AK/SK，为已有 Owner 或新建托管成员签发短期 Bearer Token，再使用短期 Token 创建项目和调用开放能力。系统集成统一推荐团队版；用户 API Key 只用于个人测试和临时调试。

## 1. 身份与凭证模型

| 对象       | 标识或凭证                                 | 生命周期      | 用途                                       |
| :------- | :------------------------------------ | :-------- | :--------------------------------------- |
| 团队       | `tenant_id`                           | 长期        | AK/SK 在服务端绑定团队，调用方不能通过参数切换团队             |
| 团队凭证     | `access_key_id` + `secret_access_key` | 长期，可过期/吊销 | 通过 HMAC 管理成员、签发成员 Token                  |
| 团队 Owner | `member_id`                           | 长期，随机且持久化 | 单大账号模式的业务身份；所有资源归属于 Owner                |
| 托管成员     | `member_id`                           | 长期，随机且持久化 | 隔离模式的成员资源标识；接入方自行保存外部用户与 `member_id` 的映射 |
| 成员临时凭证   | `access_token`                        | 短期，不可刷新   | 以成员身份调用项目、Agent、Cloud、Release 等开放能力      |

不需要 `openid`。`openid` 用于 OAuth 应用内的用户映射。Owner 模式无需保存用户映射；虚拟成员模式由接入方自行维护映射，并使用 `member_id` 调用成员管理接口。

## 2. 接入流程

1. 接入方提供团队账号，由秒悟团队在管理后台创建测试 AK/SK，配置管理 Scope、可委托业务 Scope 和 Token 最长有效期。
2. 接入方仅在可信服务端保存 AK/SK。
3. 不需要最终用户隔离时，从成员列表找到 `role=owner` 的 Owner `member_id`；需要隔离时，使用 AK/SK 创建托管成员并保存外部用户 ID → `member_id` 映射。
4. 需要调用 Meoo 能力时，使用 AK/SK 为选定的 Owner 或虚拟成员 `member_id` 签发短期 Token。
5. 使用 `Authorization: Bearer <member_token>` 调用普通 `/open/v1` 业务 API。
6. 成员冻结或删除、团队 AK/SK 吊销后，相关临时 Token 立即失效。

## 3. 创建团队 AK/SK

团队 AK/SK 的用户侧自助创建入口暂不开放，未来随“集成版”套餐提供。现阶段请联系秒悟团队创建联调测试凭证，并提供用于绑定凭证的团队账号。秒悟管理员会在管理后台核对团队 ID 与 Owner 后创建，创建时配置：

* 凭证名称和用途说明。
* 成员管理权限，例如创建、查询、冻结、删除成员和签发成员 Token。
* 允许委托给成员 Token 的业务 Scope，例如 `project.read`、`project.write`、`agent.read`、`agent.run`。
* 成员 Token 最长有效期。

`secret_access_key` 只在创建成功时展示一次。应立即写入 KMS 或 Secret Manager，不要写入数据库明文、日志、前端持久化存储或客户端应用。

凭证创建、列表、吊销属于 Meoo 内部控制面能力，不属于对外 OpenAPI 契约。接入方不应调用内部管理接口，也不应依赖其 URL 或请求结构；需要新建、轮换或吊销测试凭证时请联系秒悟团队。

## 4. HMAC 签名

团队成员管理请求必须包含：

```text theme={null}
Host: meoo.com
X-Meoo-Content-Sha256: <lowercase hex sha256>
X-Meoo-Nonce: <每次请求唯一的随机值>
X-Meoo-Timestamp: <Unix 秒级时间戳>
Authorization: MEOO-HMAC-SHA256 Credential=<AK>,SignedHeaders=host;x-meoo-content-sha256;x-meoo-nonce;x-meoo-timestamp,Signature=<signature>
```

Canonical Request：

```text theme={null}
HTTP_METHOD
NORMALIZED_PATH
CANONICAL_QUERY
CANONICAL_HEADERS
SIGNED_HEADERS
SHA256_RAW_BODY
```

签名计算：

```text theme={null}
signature = lowercase_hex(HMAC-SHA256(secret_access_key, canonical_request))
```

规则：

* Header 名按小写参与签名，签名 Header 顺序固定为 `host;x-meoo-content-sha256;x-meoo-nonce;x-meoo-timestamp`。
* GET/HEAD 的原始 Body 为空字符串。
* JSON 请求按实际发送的 UTF-8 原始字节计算摘要；计算后不能重新格式化 Body。
* Query 对名称和值进行 RFC 3986 编码后排序。
* Timestamp 只允许短时间窗口内的请求。
* Nonce 必须每次重新生成；相同 AK 下重复 Nonce 会被拒绝。

签名字段、Canonical Request 和请求示例见[鉴权说明](https://app.mintlify.com/alibaba-b47c397f/alibaba-b47c397f/~/757c99e3-fa24-43b5-848e-3c86fe532fb0)。

## 5. 选择身份并签发 Token

### 5.1 Owner 大账号模式

调用成员列表接口，选择当前团队中 `role=owner` 且 `status=active` 的成员，使用其 `member_id` 签发短期 Token。Owner Token 创建的项目、生成任务和 Release 均归属于团队 Owner；接入方自行负责最终用户与业务对象隔离。

```text theme={null}
POST /open/v1/team/members/{owner_member_id}/tokens
Authorization: MEOO-HMAC-SHA256 ...
Content-Type: application/json

{"scopes":["project.read","project.write"],"expires_in":600}
```

### 5.2 虚拟成员隔离模式

创建成员：

每个 active 虚拟成员占用一个团队席位，与普通团队成员共用套餐席位上限。冻结或删除成员释放席位，重新激活时再次校验并占用席位；席位不足时创建或激活返回 `409 quota_exceeded`，且不会产生半成品用户数据。

```text theme={null}
POST /open/v1/team/members/
Authorization: MEOO-HMAC-SHA256 ...
Content-Type: application/json

{"nickname":"接入方用户 10001"}
```

响应：

```text theme={null}
{
  "member_id": "tm_xxx",
  "nickname": "接入方用户 10001",
  "avatar": null,
  "role": "member",
  "status": "active",
  "created_at": 1787563811000
}
```

创建成员后签发 Token：

```text theme={null}
POST /open/v1/team/members/tm_xxx/tokens
Authorization: MEOO-HMAC-SHA256 ...
Content-Type: application/json

{"scopes":["project.read","project.write"],"expires_in":600}
```

响应：

```text theme={null}
{
  "access_token": "mat_xxx",
  "token_type": "Bearer",
  "expires_in": 600,
  "scope": "project.read project.write"
}
```

Owner Token 和虚拟成员 Token 都不返回 Refresh Token。`scopes` 必须同时属于平台支持范围和团队凭证的 `delegable_scopes`；`expires_in` 最低 60 秒，并受凭证 `token_ttl_max_seconds` 上限约束。

## 6. 调用业务 API

Owner 或虚拟成员 Token 与 OAuth Access Token、用户 API Key 使用相同的 Bearer 协议：

```text theme={null}
curl --request POST \
  --url "${MEOO_BASE_URL}/open/v1/projects" \
  --header "Authorization: Bearer ${MEMBER_ACCESS_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{"name":"成员项目","type":"web"}'
```

项目和后续资源归属于该成员及 AK/SK 绑定的团队。Owner Token 下资源归属于 Owner；虚拟成员 Token 下资源归属于对应托管成员。Token 不能通过请求参数切换成员、团队或工作空间。

## 7. 生命周期与安全建议

* AK/SK 只保存在可信服务端；前端只能获得短期成员 Token。
* 建议成员 Token 有效期为 5～15 分钟，并按需签发。
* Owner 模式不提供最终用户隔离，接入方必须自行校验业务对象访问权。
* 虚拟成员模式下，外部用户与 `member_id` 的映射由接入方保存；不要依赖昵称、手机号等可变字段。
* 成员离职、封禁或解绑时调用冻结或删除接口；已有 Token 会立即失效。
* AK/SK 泄露时立即吊销并创建新凭证。
* 收到 401 时重新签发 Token；不要尝试刷新成员 Token。
* 对非幂等调用自行保存业务幂等状态；HMAC Nonce 只负责阻止同一签名被重放。

成员接口的完整字段与错误说明见[团队成员 API](https://app.mintlify.com/alibaba-b47c397f/alibaba-b47c397f/~/c0ca3603-79ca-40fa-aa93-0b6bc8be9ff9)，通用错误、分页和追踪规则见[通用协议](https://app.mintlify.com/alibaba-b47c397f/alibaba-b47c397f/~/de50f6a7-356b-405b-9dbe-374db0e46b3e)。