# 成员

在 AISIX Enterprise 或 AISIX Cloud 中，成员属于一个组织，代表负责控制面管理、API Key、用量和限制的人员或服务所有者。

共享控制面支持两种成员加入方式，适用产品有所不同：

* 当成员需要登录控制台时，邀请该成员。
* 当你需要一个不登录控制台的 API Key 所有者时，直接创建成员。这种方式仅在 AISIX Enterprise 中可用。

两种方式都会创建组织成员。区别在于该成员是否会收到邀请，以及是否可以使用控制台。管理员之后可以为直接创建的成员[启用登录](#enable-sign-in-or-reset-a-password)。

在 AISIX Cloud 上，成员通过邀请、[单点登录](https://docs.apiseven.com/ai-gateway/cloud/single-sign-on.md)或 [SCIM 目录同步](https://docs.apiseven.com/ai-gateway/cloud/scim-directory-sync.md)加入组织，不能直接创建成员。

AISIX Enterprise 控制面不开放自行注册：除非组织的[单点登录](https://docs.apiseven.com/ai-gateway/cloud/single-sign-on.md)会在登录时自动添加新成员，否则邀请是新用户创建账号的唯一途径。

配置单点登录后，成员也可以通过身份提供方登录，而不必使用密码；受邀者也可以通过 SSO 登录来接受邀请。

## 邀请成员[​](#invite-a-member "邀请成员的直接链接")

当某个人需要控制台访问权限来管理资源、查看用量或管理组织时，请使用邀请方式。

1. 打开 **成员**，选择 **邀请成员**。
2. 输入成员的 **邮箱**，并在 **角色** 中选择一个或多个角色。默认预选 **受限成员**。不分配角色时，受邀者加入后没有任何访问权限。
3. 选择 **发送邀请**。

受邀者接受邀请时获得邀请中的全部角色，作为手动[角色分配](#assign-roles-to-a-member)。谁可以用哪些角色邀请：

* 角色可以创建成员的人，都可以用 **成员** 或 **受限成员** 邀请。
* 用 **管理员** 或自定义角色邀请，需要内置的管理员或所有者角色。
* 用 **所有者** 邀请，需要所有者角色。

通过 Admin API 时，`POST /invitations` 以 `roles` 数组接收角色。省略该字段时以 `restricted_member` 邀请，传空数组则不分配任何角色。

邮件投递方式因产品而异。AISIX Cloud 使用由 API7 运营的邮件中继。AISIX Enterprise 需要由运维人员[配置 SMTP 中继](https://docs.apiseven.com/ai-gateway/on-premises/email.md)；未配置时，控制台会提供生成好的邀请链接，供管理员自行分发。

邮件投递可用时，控制面会把邀请链接发送给受邀人。邀请卡片会确认中继已接受邮件。若投递失败，卡片会显示连接、TLS、身份认证等失败原因或中继的拒绝消息；邀请本身仍然有效。

两种情况下，卡片都只显示一次邀请链接，你可以复制它并通过可信渠道转交。任何持有该链接的人都能打开这份邀请，因此请像对待凭据一样对待它。控制面只存储链接的哈希值，离开页面后无法再次显示；如需新链接，请[重新发送邀请](#resend-an-invitation)。

打开链接后，受邀人会看到是谁邀请的、将要加入哪个组织、以及获得哪些角色。尚未拥有账号的受邀人可以直接从该页面注册——邮箱已自动填入且不可修改——注册完成后会回到邀请页面。在邀请流程中，账号只能通过邀请链接创建：注册请求会携带邀请 Token，当邀请已不处于待接受状态、已过期或发给了其他地址时，控制面会拒绝该请求。未通过邀请打开注册页面时，页面会提示注册已关闭。加入组织始终需要显式点击 **接受邀请**：仅打开链接不会改变成员关系，因此已登录其他组织的用户点开链接也不会被切换过去。

邀请与你填写的邮箱绑定。只有使用该邮箱的账号才能接受邀请；其他账号打开链接时，会看到该邀请是发给哪个邮箱的，并可以切换到该账号登录。在受邀人接受前，该邀请会停留在 **待处理邀请** 标签页。

已经是组织成员的邮箱无法再被邀请。接受邀请不会修改已有成员的角色，这样的邀请不会产生任何效果。请直接在成员列表中[分配角色](#assign-roles-to-a-member)。邀请也无法恢复已被 [SCIM 目录同步](https://docs.apiseven.com/ai-gateway/cloud/scim-directory-sync.md#what-a-deactivated-member-loses)停用的成员：兑换邀请会返回 `403` 和错误码 `MEMBER_DEACTIVATED`。

### 邀请有效期[​](#invitation-lifetime "邀请有效期的直接链接")

邀请在发出 7 天后过期。在此之前，它会停留在 **待处理邀请** 标签页，你可以在这里吊销它，使链接立即失效。吊销邀请需要 `members` 的 `delete`，与移除成员不同，它不需要所有者角色。

该标签页默认只列出仍然有效的邀请。勾选 **显示历史邀请（已接受、已吊销、已过期）** 后，还会显示已接受、已吊销和已过期的邀请。如果需要清理记录，已过期的邀请也可以在这里吊销。

已过期的邀请不会继续占用该邮箱：再次邀请同一个人会签发新的链接，并作废那条已过期的邀请，后者仍会显示在 **显示历史邀请（已接受、已吊销、已过期）** 中。只有仍然处于待接受且未过期的邀请，才会阻止对同一邮箱再次发起邀请。

### 重新发送邀请[​](#resend-an-invitation "重新发送邀请的直接链接")

在待接受的邀请上，或在 **显示历史邀请（已接受、已吊销、已过期）** 中列出的已过期邀请上，选择 **重新发送** 即可重新签发该邀请。重新发送会生成新链接，之前签发的链接随即失效，邀请的有效期从重新发送时起重新计算 7 天。邮件投递可用时，新链接会再次通过邮件发给受邀人；无论邮件是否可用，卡片都会显示新链接。

你只能重新发送你本可以用相同角色创建的邀请。如果该邮箱在此期间已通过其他方式加入组织，则无法重新发送；`cp-api` 会返回 `409` 和错误码 `ALREADY_MEMBER`。

### 邀请邮件数量限制[​](#invitation-email-limit "邀请邮件数量限制的直接链接")

邮件投递可用时，每个账号在每个滚动小时内可发送的邀请邮件数量有限，默认为 50 封。该限制统计账号所属的所有组织，创建邀请和重新发送邀请都会计数。超出限制时，邀请会被拒绝并返回 `429`，不会创建或重新签发任何邀请。AISIX Enterprise 运维人员可以通过 `api.smtp.invitationLimitPerHour` 设置该限制，参见[邀请邮件数量限制](https://docs.apiseven.com/ai-gateway/on-premises/email.md#invitation-email-limit)。

## 在 AISIX Cloud 上注册[​](#sign-up-for-aisix-cloud "在 AISIX Cloud 上注册的直接链接")

在 AISIX Cloud 上，任何人都可以在注册页面创建账号，但必须先确认邮箱地址，账号才能使用：

1. 填写名称、邮箱地址和密码完成注册。页面随后提示查收邮件，此时还不会建立会话。
2. 打开邮件中的验证链接。它会打开登录页面，并预先填好邮箱地址。
3. 使用注册时设置的密码登录。这会完成邮箱验证并登录。

验证链接 24 小时内有效，只能使用一次。它需要用账号当前的密码登录才能完成，因此即使链接落到别人手里，没有密码也无法使用。仅打开链接不会改变任何状态。

在邮箱地址验证之前，使用密码登录会被拒绝，返回 `403`，错误码为 `EMAIL_NOT_VERIFIED`，登录页面会提供重新发送验证邮件的入口。无效、已过期、已使用或已被更新的链接取代的链接会被拒绝，错误码为 `EMAIL_VERIFICATION_LINK_INVALID`。密码错误时，无论邮箱是否已验证，都只返回 `INVALID_EMAIL_OR_PASSWORD`，因此登录尝试不会暴露某个地址是否已验证。

需要新链接时，在查收邮件页面或登录页面选择 **重新发送验证邮件**。每个新链接都会使之前的链接失效；但如果距离上一个链接不足一分钟，新请求会被忽略，之前的链接仍然有效。无论该地址是否有待验证的账号，页面显示的提示都相同，因此无法借此探测哪些邮箱已注册。

用一个账号仍未验证的地址再次注册，会替换之前的注册：新的名称和密码生效，该账号的会话全部结束，并发送新的验证链接。账号已验证的地址，或属于没有密码的账号（例如由 SSO 或 SCIM 创建的账号）的地址，不能再次注册。

[重置忘记的密码](#reset-a-forgotten-password)同样会验证邮箱地址，因为重置链接是从该邮箱中打开的。

AISIX Enterprise 不验证邮箱地址，那里的账号都来自[邀请](#invite-a-member)。

## 重置忘记的密码[​](#reset-a-forgotten-password "重置忘记的密码的直接链接")

有密码但忘记密码的成员可以在登录页重置密码。AISIX Cloud 使用由 API7 运营的邮件中继发送邮件；AISIX Enterprise 需要由运维人员配置 SMTP 中继：

1. 在登录页选择 **忘记密码？**。
2. 输入账号的邮箱地址，选择 **发送重置链接**。
3. 打开邮件中的链接并设置新密码。新密码适用与注册时相同的密码规则。

无论该邮箱是否属于某个账号，页面显示的提示都相同，因此无法借此探测哪些邮箱已注册。重置链接：

* 有效期为一小时；
* 只能使用一次；
* 会替换该账号之前的所有重置链接；但如果距离上一次请求不足一分钟，新请求会被忽略，之前的链接仍然有效。

重置密码后，该账号在所有设备上的所有会话都会退出登录。请使用新密码重新登录。在 AISIX Cloud 上，重置密码还会把邮箱地址标记为已验证。

没有邮件服务时，忘记密码页面会提示用户联系管理员，不提供表单。

没有密码的账号不会收到重置邮件，包括[直接创建的成员](#create-a-member-directly)、通过 [SCIM](https://docs.apiseven.com/ai-gateway/cloud/scim-directory-sync.md) 创建的成员、从[AISIX Enterprise 脱敏备份](https://docs.apiseven.com/ai-gateway/cloud/organization-backup-and-restore.md#finish-a-redacted-restore)恢复的账号，以及在 Google 和 GitHub 登录选项移除前只通过 Google 或 GitHub 登录的用户。管理员可以改为为他们[启用登录](#enable-sign-in-or-reset-a-password)。

## 启用登录或重置密码[​](#enable-sign-in-or-reset-a-password "启用登录或重置密码的直接链接")

在 AISIX Enterprise 控制面上，管理员可以向成员提供一个一次性链接，由成员在该链接上自行设置密码。管理员既看不到也无法指定这个密码。

**成员** 列表显示每位成员的登录方式。请结合组织的[单点登录](https://docs.apiseven.com/ai-gateway/cloud/single-sign-on.md)连接解读这些状态：

* **可登录**，括号中列出成员的登录方式：**密码**、**SSO** 或两者兼有。**SSO** 表示该成员已关联到组织已启用的 SSO 连接上的某个身份，这一关联在成员首次单点登录时建立。
* **通过 SSO 登录**：组织的 SSO 连接已启用，而成员既没有密码、也尚未建立 SSO 关联。身份提供方会在成员首次单点登录时按其邮箱地址放行。
* **密码 · 需要 SSO**：连接强制单点登录时，只有密码的非所有者成员。仅凭密码无法进入组织，必须通过 SSO 登录。只有能读取 SSO 设置的组织所有者和管理员能看到这个标记，其他查看者看到的是 **可登录（密码）**。
* **不可登录**：组织没有启用 SSO 连接，而成员既没有密码、也没有 SSO 关联。

在 AISIX Enterprise 和 AISIX Cloud 中，每一行还会显示 **已开启双因素认证** 或 **未开启双因素认证**，表示该成员的账号是否开启了[双因素认证](https://docs.apiseven.com/ai-gateway/cloud/password-policy-and-two-factor-authentication.md)。

已停用的成员只显示 **已停用**，不显示登录标记，也没有登录相关操作。对于其他成员，行操作取决于成员是否有密码：

* **重置密码**：用于已有密码的成员。在成员设置新密码之前，当前密码仍然有效。
* **设置密码**：用于没有密码、但可以通过 SSO 登录的成员。设置密码后成员多了一种登录方式，但在强制单点登录时，仅凭密码无法进入组织。
* **开通登录**：用于无法以任何方式登录的成员，例如[直接创建的成员](#create-a-member-directly)、通过 [SCIM](https://docs.apiseven.com/ai-gateway/cloud/scim-directory-sync.md) 创建的成员，或从 AISIX Enterprise 脱敏备份恢复的成员。

选择其中任一操作后，页面会显示一张包含该链接的卡片，你可以复制链接。[AISIX Enterprise 配置了邮件](https://docs.apiseven.com/ai-gateway/on-premises/email.md)时，控制面还会以组织的语言（组织未设置时为部署默认语言）把链接发送到成员邮箱，卡片会显示发送到了哪里，或邮件未送达的原因。没有邮件服务时不会发送任何内容，请通过可信渠道自行把链接转交给成员。卡片只显示一次链接。

该链接：

* 有效期为 72 小时；
* 只能使用一次；
* 在你为同一成员签发更新的链接、该成员通过 **忘记密码？** 申请重置、该成员的角色发生变化、你移除该成员，或 [SCIM 目录同步](https://docs.apiseven.com/ai-gateway/cloud/scim-directory-sync.md)停用或删除该成员时失效。无论角色变化是手动做出的、由 SSO 或 SCIM 做出的，还是因为成员所在的团队添加或移除了角色，都算在内。把成员加入团队或移出团队不会使链接失效；
* 只有当持有人仍是签发组织的有效成员时才能使用，否则会被当作无效链接拒绝；
* 只有在成员已经是所有者时由所有者签发的链接，才能为所有者设置密码。从 1.11.0 开始，签发时成员还不是所有者、使用时已成为所有者的链接会被当作无效链接拒绝，并随之失效。升级到 1.11.0 之前签发的链接没有记录签发者，因此其中目标已是所有者的未使用链接都会失效，需要由所有者重新签发。

无法为已停用的成员签发链接：请求返回 `400` 和错误码 `INVALID_REQUEST`，也不会发送邮件。

成员设置密码后，该账号的所有会话都会结束，成员使用新密码登录。未使用而过期的链接不会产生任何变化。无论哪种情况，成员的团队、角色和 API Key 都不受影响。

签发链接需要[设置密码链接权限](https://docs.apiseven.com/ai-gateway/cloud/custom-roles.md#who-can-change-access)（`member_passwords`），内置的 `admin` 和 `owner` 角色持有它，自定义角色也可以包含它。更新成员的权限不包括它。由于持有链接的人可以接管该账号，只有所有者可以为所有者签发链接。

如需通过自动化签发链接，请使用持有该权限的成员的、具有 `write` 权限范围的 [Admin Token](https://docs.apiseven.com/ai-gateway/cloud/admin-tokens.md) 调用 `POST /members/{user_id}/set_password_link`，其中 `user_id` 取自[成员列表](#list-members-with-the-api)，`AISIX_CP` 和 `AISIX_TOKEN` 的取值见[使用 API](#use-the-api)。响应中包含 `link`、其 `expires_at`、`action`（`enable_sign_in` 或 `reset_password`）以及 `email_delivery`：

```
export USER_ID="MEMBER_USER_ID"



curl -X POST "${AISIX_CP}/members/${USER_ID}/set_password_link" \

  -H "Authorization: Bearer ${AISIX_TOKEN}"
```

## 直接创建成员[​](#create-a-member-directly "直接创建成员的直接链接")

在 AISIX Enterprise 控制面上，当服务、应用或开发者需要拥有 API Key 但不需要控制台访问权限时，可以直接创建成员。

AISIX Cloud 不提供直接创建成员：**成员** 页面没有 **创建用户** 按钮，`POST /members` 返回 `404`。AISIX Cloud 上的账号由所有组织共用，直接创建的成员会持有一个其主人从未确认过的地址的账号，还会阻止此人自行注册。请改为邀请此人，或通过 [SCIM 目录同步](https://docs.apiseven.com/ai-gateway/cloud/scim-directory-sync.md)预配。

直接创建的成员：

* 会立即激活，不需要邀请链接或确认步骤。
* 获得创建时选择的角色，未另选时为 **受限成员**。
* 可以加入团队并分配 API Key。
* 可以受限流和预算治理。
* 没有密码，因此在管理员[启用登录](#enable-sign-in-or-reset-a-password)之前无法登录控制台。

该成员仍然有名称和邮箱。请使用能够识别责任人、服务或应用所有者的值，以便正确归因用量和限制。

[]()

### 在控制台中操作[​](#in-the-dashboard "在控制台中操作的直接链接")

1. 打开 **成员**，选择 **创建用户**。
2. 输入能够识别责任归属的 **名称** 和 **邮箱**。
3. 在 **角色** 中选择一个或多个角色。默认预选 **受限成员**，列表中只有你可以授予的角色。不分配角色时，该用户加入后没有任何访问权限。
4. 选择 **创建用户**。

![创建用户表单，角色�中已预选受限成员，角色字段已框出](https://static.apiseven.com/uploads/2026/11/19/RRDaVAmJ_create-user-role.webp)

可以授予哪些角色，与[邀请](#invite-a-member)的规则相同：角色可以创建成员的人，都可以授予 **成员** 或 **受限成员**；授予 **管理员** 或自定义角色，需要内置的管理员或所有者角色；授予 **所有者**，需要所有者角色。成员获得的角色作为手动[角色分配](#assign-roles-to-a-member)记录。

成员会立即出现在列表中。随后你可以[将该成员加入团队](https://docs.apiseven.com/ai-gateway/cloud/teams.md#add-and-manage-members)，并从承载其流量的环境中签发 API Key。

### 使用 API[​](#use-the-api "使用 API的直接链接")

当需要通过自动化预配成员时，请使用 API。

使用具有 `write` 权限范围的[组织 Admin Token](https://docs.apiseven.com/ai-gateway/cloud/admin-tokens.md)认证。Admin Token 的作用域绑定到一个组织，因此请求不需要额外的组织请求头。

```
# AISIX_CP 包含 /api，且不含尾部斜杠

# 本地 AISIX Enterprise 快速入门使用 http://localhost:8080/api

export AISIX_CP="YOUR_AISIX_CONTROL_PLANE_API_URL"

export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
```

创建成员：

```
curl -X POST "${AISIX_CP}/members" \

  -H "Authorization: Bearer ${AISIX_TOKEN}" \

  -H "Content-Type: application/json" \

  -d '{

    "name": "Responsible Person",

    "email": "svc-payments@example.com",

    "roles": ["restricted_member"]

  }'
```

成功调用会返回 `201 Created` 和新成员：

```
{

  "member": {

    "id": "8f3b2a1c-9d4e-4f6a-b7c8-1e2d3f4a5b6c",

    "user_id": "2c7d6e5f-4a3b-4c2d-8e1f-9a0b1c2d3e4f",

    "email": "svc-payments@example.com",

    "display_name": "Responsible Person",

    "roles": [

      {

        "role": "restricted_member",

        "source": "manual"

      }

    ],

    "team_roles": [],

    "sign_in_methods": []

  }

}
```

邮箱地址必须有效，并且在部署内唯一。对于应用所有者，可以使用类似 `svc-payments@example.com` 的合成地址。复用已有邮箱会返回 `409 Conflict`。

`roles` 接收内置角色或已有的自定义角色。省略该字段时，成员以 `restricted_member` 创建；传空数组则创建一个没有任何角色的成员。授予你无权授予的角色会返回 `403`，错误码为 `FORBIDDEN`；名称既不是内置角色也不是已有自定义角色时返回 `400`，错误码为 `INVALID_REQUEST`。在控制面 1.11.0 之前，直接创建的成员一开始始终持有 `member` 角色。

将调用方 API Key 归属到该成员时，请把成员关系的 `id` 填入密钥的 `user_id`。成员响应中还包含账号的 `user_id`，它是供成员路由和团队成员关系使用的另一个标识符。不要用账号 ID 代替调用方密钥归属所需的成员关系 ID。

## 等待加入的成员[​](#members-waiting-to-join "等待加入的成员的直接链接")

在 AISIX Cloud 上，[SCIM 目录同步](https://docs.apiseven.com/ai-gateway/cloud/scim-directory-sync.md)把地址位于组织[已验证域名](https://docs.apiseven.com/ai-gateway/cloud/organization-domains.md)以外的预配用户记录为等待加入的成员，并向该地址发送邀请。**成员** 页面在成员列表下方的 **待加入** 区块中列出这些人，显示其邮箱地址、角色、目录 ID 以及是否处于激活状态，邀请则出现在 **待处理邀请** 标签页中。没有人等待加入时，该区块不显示。

本人接受邀请，或以目录中对应的身份关联组织的单点登录后，等待加入的成员即成为正式成员。请在身份提供方中管理这些成员。参见[等待加入的成员](https://docs.apiseven.com/ai-gateway/cloud/scim-directory-sync.md#members-waiting-to-join)。

## 为成员分配角色[​](#assign-roles-to-a-member "为成员分配角色的直接链接")

一名成员可以持有多个[角色](https://docs.apiseven.com/ai-gateway/cloud/custom-roles.md)，这些角色叠加生效。**成员** 列表以标签形式显示每位成员的角色。没有任何角色的成员没有任何访问权限。

要修改成员的角色，打开 **成员**，在该成员所在行选择 **角色**：

* **已分配角色** 列出成员直接持有的角色，每个都带来源：**手动**、**SSO** 或 **SCIM**。选择 **移除** 可以移除手动分配的角色。
* 要添加角色，从 **选择角色** 中选择，然后选择 **添加角色**。
* **来自团队** 以“团队 → 角色”的形式列出成员通过团队持有的角色。这些角色请在[团队](https://docs.apiseven.com/ai-gateway/cloud/teams.md#give-a-team-roles)上修改，而不是在这里。

由[单点登录](https://docs.apiseven.com/ai-gateway/cloud/single-sign-on.md#map-idp-attributes-to-roles)或 [SCIM 目录同步](https://docs.apiseven.com/ai-gateway/cloud/scim-directory-sync.md#assign-roles-to-synced-members)分配的角色被锁定：它们归身份提供方所有，提示中会说明请在身份提供方中修改。成员可能同时以手动方式和由身份提供方持有同一个角色，此时移除手动分配后仍保留受管理的那个。

添加和移除角色需要 `role_assignments` 权限，默认只有所有者持有。没有该权限时，**角色** 区块为只读并说明原因。只有所有者能在可选角色中看到 **所有者**，最后一名所有者不能失去该角色。

在成员所在行选择 **生效权限**，可以查看其全部角色叠加后的结果以及每条规则的来源。参见[查看生效权限](https://docs.apiseven.com/ai-gateway/cloud/custom-roles.md#check-effective-permissions)。

### 使用 API 分配角色[​](#assign-roles-with-the-api "使用 API 分配角色的直接链接")

成员角色路由使用成员的 `user_id`：

```
export USER_ID="MEMBER_USER_ID"



curl -sS -X POST "${AISIX_CP}/members/${USER_ID}/roles" \

  -H "Authorization: Bearer ${AISIX_TOKEN}" \

  -H "Content-Type: application/json" \

  -d '{"role": "auditor"}'



curl -sS -X DELETE "${AISIX_CP}/members/${USER_ID}/roles/auditor" \

  -H "Authorization: Bearer ${AISIX_TOKEN}"
```

两者都返回成员的 `roles`（每个带 `source`）和 `team_roles`（每个带来源团队）。添加成员已经手动持有的角色不会有任何变化。移除成员仅由 SSO 或 SCIM 持有的角色会返回 `409` 和错误码 `MANAGED_ASSIGNMENT`，移除最后一名所有者会返回 `409` 和 `LAST_OWNER`。

`GET /members` 中的每位成员都带有同样的 `roles` 和 `team_roles`。`PATCH /members/{user_id}` 只修改成员标签，不接受角色。

[]()

## 浏览和搜索成员[​](#browse-and-search-members "浏览和搜索成员的直接链接")

**成员** 列表支持搜索和分页，便于管理大型组织。

* 使用搜索框按名称或邮箱过滤。搜索在服务端执行，因此会匹配所有页面，而不只匹配当前页面中的行。
* 使用列表下方控件调整页面大小或在页面之间切换。

### 使用 API 列出成员[​](#list-members-with-the-api "使用 API 列出成��员的直接链接")

复用上面导出的 `AISIX_CP` 和 `AISIX_TOKEN`。此请求使用具有 `read` 权限范围的 Token 即可。

```
curl "${AISIX_CP}/members?page=1&page_size=20&q=payments" \

  -H "Authorization: Bearer ${AISIX_TOKEN}"
```

查询参数都是可选的：

* `q`：对成员名称和邮箱执行不区分大小写的匹配。
* `team_id`：只返回该团队的成员。不属于本组织的团队没有成员，结果为空。
* `exclude_team_id`：只返回不在该团队的成员。不属于本组织的团队不排除任何人。
* `status`：只返回该状态的成员，取值为 `active` 或 `deactivated`。
* `page`：从 1 开始的页码。需要同时设置 `page_size`；单独设置 `page` 会返回 `400`。
* `page_size`：页面大小，最大为 `200`。如果同时省略 `page` 和 `page_size`，则禁用分页，并在单个响应中返回所有成员。

这些筛选条件可以相互组合，也可以和分页组合。不带任何参数的请求仍返回所有成员。

响应会在分页结构中包装成员列表：

```
{

  "data": [],

  "total": 128,

  "page": 1,

  "page_size": 20,

  "owner_count": 2

}
```

`total` 是所有页面中匹配过滤条件的成员数量，`owner_count` 是组织中的所有者数量。在 AISIX Enterprise 控制面上，每个成员还带有 `sign_in_methods`，列出该成员可以使用的登录方式：成员有控制台密码时包含 `password`，成员已关联到组织已启用的单点登录连接上的身份时包含 `sso`。两者都没有时为空，直到通过[设置密码链接](#enable-sign-in-or-reset-a-password)设置了密码，或成员通过单点登录登录。在两种产品中，每个成员都带有 `two_factor_enabled`，成员的账号开启了[双因素认证](https://docs.apiseven.com/ai-gateway/cloud/password-policy-and-two-factor-authentication.md)时为 `true`。

### 按 ID 查询成员[​](#look-up-members-by-id "按 ID 查询成员的直接链接")

`POST /members/lookup` 按成员关系 `id`、`user_id` 或两者查询成员，这样显示成员名称的页面无需获取完整列表：

```
curl -sS -X POST "${AISIX_CP}/members/lookup" \

  -H "Authorization: Bearer ${AISIX_TOKEN}" \

  -H "Content-Type: application/json" \

  -d '{"ids": ["51ce4a7e-b5c5-4b18-8936-9f235765357f"], "user_ids": []}'
```

一次请求的两个列表合计最多 500 个 ID，超过返回 `400`。响应的 `data` 数组中每个成员只出现一次，形状与列表项相同，已停用的成员也会返回并带状态。响应中没有的 ID 表示该成员不在本组织：已被移除，或从未属于本组织。此请求只读取数据，因此虽然是 `POST`，使用具有 `read` 权限范围的 Token 即可。

### 获取自己的成员信息[​](#get-your-own-membership "获取自己的成员信息的直接链接")

`GET /members/me` 以 `{"member": {}}` 的形式返回调用方在组织中的成员信息，其中的对象与列表项形状相同。Admin Token 返回创建它的成员。任何成员都可以调用它，不论持有什么角色。`GET /members/me/permissions` 返回调用方的[生效权限](https://docs.apiseven.com/ai-gateway/cloud/custom-roles.md#check-effective-permissions)。

## 为成员设置标签[​](#tag-a-member "为成员设置标签的直接链接")

在成员行中选择 **标签**，即可设置该成员的[成本归属标签](https://docs.apiseven.com/ai-gateway/cloud/cost-attribution-tags.md)。通过该成员拥有的调用方 API Key 发出的请求，凡 Key 和其团队都没有设置、[JWT Claim](https://docs.apiseven.com/ai-gateway/cloud/cost-attribution-tags.md#read-tags-from-jwt-claims) 也没有提供的标签，都取成员的值。角色可以更新成员的人可以通过 `PATCH /members/{user_id}` 的 `tags` 修改成员标签，直接创建成员时 `POST /members` 也接受 `tags`。由 [SCIM 目录同步](https://docs.apiseven.com/ai-gateway/cloud/scim-directory-sync.md)管理的成员，其标签仍然可以编辑，因为目录同步不同步标签。

## 移除成员[​](#remove-a-member "移除成员的直接链接")

在成员行上选择移除操作。移除成员会一并撤销其组织成员资格、角色，以及在所有团队中的成员关系。只有所有者可以移除成员。

同时会**禁用该成员拥有的所有 API Key**，并且该变更会传播到网关，因此这些凭证将无法在网关通过身份认证，而不只是无法在控制台中使用。这与身份提供方通过 [SCIM](https://docs.apiseven.com/ai-gateway/cloud/scim-directory-sync.md) 触发的预配撤销是同一套行为——从控制台移除和从目录移除，现在会让组织处于相同的状态。

该成员的[预算](https://docs.apiseven.com/ai-gateway/traffic-controls/budgets.md)和作用于该成员的[经典限流策略](https://docs.apiseven.com/ai-gateway/traffic-controls/rate-limit-policies.md#manage-classic-single-scope-policies)会被删除，该成员在每个“团队中的每个成员”预算下自己的计数也会被删除。确认弹窗会按名称列出这些预算和策略。

这些 Key 是被禁用而不是被删除，因此其用量历史仍可用于报表。运维此前手工禁用的 Key 会保留原有的禁用来源。如果这个人离开后其凭证仍需继续承载流量（例如以其账号创建的应用 Key），请在移除成员之前重新绑定或重建它们。

如果该成员的账号没有密码，且不属于其他任何组织，移除成员时也会删除该账号，使其邮箱地址可以再次使用。这包括[直接创建的成员](#create-a-member-directly)、通过 [SCIM](https://docs.apiseven.com/ai-gateway/cloud/scim-directory-sync.md) 预配的成员，以及首次登录时由[单点登录](https://docs.apiseven.com/ai-gateway/cloud/single-sign-on.md)创建的成员。有密码的账号，或仍是其他组织成员的账号，会保留。[删除组织](https://docs.apiseven.com/ai-gateway/cloud/organizations-and-environments.md#delete-an-organization)时，每个成员的账号都按同样的规则处理。

[]()

## 下一步[​](#next-steps "下一步的直接链接")

继续阅读[团队](https://docs.apiseven.com/ai-gateway/cloud/teams.md)，了解如何为成员分组以便归因和实施共享控制；或继续阅读[角色与权限](https://docs.apiseven.com/ai-gateway/cloud/custom-roles.md)，了解如何控制成员权限。如果成员应由身份提供方管理，请使用 [SCIM 目录同步](https://docs.apiseven.com/ai-gateway/cloud/scim-directory-sync.md)；如果成员应通过身份提供方登录，请使用[单点登录（SAML）](https://docs.apiseven.com/ai-gateway/cloud/single-sign-on.md)。如需设置密码策略或要求开启双因素认证，请参见[密码策略与双因素认证](https://docs.apiseven.com/ai-gateway/cloud/password-policy-and-two-factor-authentication.md)。
