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

# 团队成员 API

团队成员 API 使用团队 AK/SK 的 HMAC 签名，不接受 OAuth Token、用户 API Key 或成员 Bearer Token。基础路径：`/open/v1/team/members`。

## Scope

| Scope                     | 能力           |
| :------------------------ | :----------- |
| `team.member.read`        | 查询成员列表和详情    |
| `team.member.create`      | 创建托管成员       |
| `team.member.update`      | 激活或冻结成员      |
| `team.member.freeze`      | 凭证可配置的冻结管理能力 |
| `team.member.delete`      | 删除成员         |
| `team.member.token.issue` | 签发成员临时 Token |

## 创建成员

```text theme={null}
POST /open/v1/team/members/
```

所需 Scope：`team.member.create`。

**字段说明**

* `nickname`（string，必填）：1～50 个字符
* `avatar`（string | null，可选）：头像 URL，最长 512 字符

成功返回成员对象。创建的成员角色固定为 `member`，并加入团队首个可用工作空间。

虚拟成员与普通团队成员共用团队席位：创建一个 active 虚拟成员会占用一个席位。创建时服务端会在团队锁内重新检查席位，席位已满则整个创建事务回滚，不会留下用户或成员数据。冻结或删除成员会释放席位；重新激活时会再次校验并占用席位。

## 查询成员列表

```text theme={null}
GET /open/v1/team/members/?page_size=20&page_token=...
```

所需 Scope：`team.member.read`。

**Query说明**

* `page_size`（integer，可选）：默认 20，范围 1～100
* `page_token`（string，可选）：上一页返回的不透明令牌

响应：

```text theme={null}
{
  "members": [
    {
      "member_id": "tm_xxx",
      "nickname": "成员 A",
      "avatar": null,
      "role": "member",
      "status": "active",
      "created_at": 1787563811000
    }
  ],
  "next_page_token": "opaque_token"
}
```

## 获取成员详情

```text theme={null}
GET /open/v1/team/members/{member_id}
```

所需 Scope：`team.member.read`。不存在或不属于当前 AK/SK 绑定团队时返回 404。

## 更新成员状态

```text theme={null}
PATCH /open/v1/team/members/{member_id}
Content-Type: application/json

{"status":"freeze"}
```

所需 Scope：`team.member.update`。`status` 支持：

* `active`：恢复成员。
* `freeze`：冻结成员，并立即撤销其已有委托 Token。

团队 Owner 不能通过该接口修改。

## 删除成员

```text theme={null}
DELETE /open/v1/team/members/{member_id}
Content-Type: application/json
X-Meoo-Content-Sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
```

所需 Scope：`team.member.delete`。删除采用状态失效语义，并立即撤销该成员已有委托 Token。团队 Owner 不能删除。

调用要求：本接口无需请求体，但当前实现要求显式发送 Content-Type: application/json。请求体保持零字节，不需要附加 \{}；X-Meoo-Content-Sha256 及 HMAC Canonical Request 的 Body 摘要均使用空字节串的 SHA256（示例所示值）。Authorization、X-Meoo-Timestamp、X-Meoo-Nonce 等签名 Header 仍按团队 HMAC 规则发送；上述示例仅展示本接口特别要求的 Header。未发送 Content-Type 的空 DELETE 可能返回 401 invalid\_signature（请求 Body 摘要无效）。

该接口不会自动删除或转交成员名下的项目。如需删除项目，使用“用户与项目 API”中的删除项目接口（DELETE /open/v1/projects/\{project\_id}，需要 project.write 和项目删除权限），应在撤销成员访问权限前完成，或由仍具备删除权限的用户操作。

[用户与项目 API](https://docs.dingtalk.com/i/nodes/Qnp9zOoBVBDEydnQUeDjoale81DK0g6l)

## 签发成员临时 Token

```text theme={null}
POST /open/v1/team/members/{member_id}/tokens
Content-Type: application/json

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

所需 Scope：`team.member.token.issue`。

**字段说明**

* `scopes`（string\[ ]，必填）：明确的业务 Scope；不能使用 `*`
* `expires_in`（integer，可选）：最低 60 秒，最终值不超过凭证配置上限

响应：

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

该 Token 不可刷新。成员非 active、团队凭证被吊销/标记泄露、团队不可用或授权 Scope 已被收回后，Token 均不可继续使用。

## 常见错误

| HTTP    | Code                  | 说明                       |
| :------ | :-------------------- | :----------------------- |
| 400     | `invalid_request`     | 参数不合法                    |
| 400/403 | `invalid_scope`       | Scope 不受支持或不允许委托         |
| 401     | `invalid_signature`   | AK/SK、摘要、时间戳、Nonce 或签名无效 |
| 401     | `invalid_token`       | 成员 Token 失效或过期           |
| 403     | `insufficient_scope`  | 团队凭证缺少管理 Scope           |
| 403     | `member_inactive`     | 成员已冻结或删除                 |
| 409     | `quota_exceeded`      | 团队成员席位已满，不能创建虚拟成员        |
| 503     | `server_error`        | 团队席位额度暂时不可用，可稍后重试        |
| 404     | `not_found`           | 成员不存在或不属于当前团队            |
| 429     | `rate_limit_exceeded` | 请求频率超过限制                 |

HMAC 生成方法和完整调用流程见[团队系统集成指南](https://app.mintlify.com/alibaba-b47c397f/alibaba-b47c397f/~/8b2e4f11-3395-4dd1-b58e-2e6935dd1392)。