managing-end-users

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Managing End Users

管理终端用户

An end user is a person's access record for MCP servers only: they sign in to the account's MCP servers through Celigo OAuth (routed to the company's identity provider where one is set up) and get no workspace access. What each one may call is the union of their grants -- direct, through groups, through roles, and through capability sets. Concerns when managing end users:

Records -- invite, accept, revoke; identity-provider provisioning (JIT, SCIM); suspending
Grants -- capability strings per MCP server, on a person, a group, or a role
Groups and roles -- shared access, and memberships that are manual or synced from the identity provider
Capability sets -- named bundles of a server's items, granted as one unit
Effective access -- the compiled result, per person or per server
End users' own connections -- the credentials each person supplies where a server asks for them

End users are a separate record type from workspace users. The same person can hold both -- the end-user record then shows

hasWorkspaceShare: true

-- and changing or removing one never touches the other. The account owner is never an end user: the owner reaches every server without a record, is never listed, and can't be invited. Only the owner and administrators manage end users, groups and roles.

终端用户是仅针对 MCP 服务器的个人访问记录：他们通过 Celigo OAuth 登录账户的 MCP 服务器（如果配置了公司的身份提供商，则会路由到该身份提供商），但不会获得任何 workspace 访问权限。每个人可以调用的内容是其各项授权的并集，包括直接授权，以及通过 Group、Role 和 Capability Set 获得的授权。管理终端用户时需要关注：

记录——邀请、接受、撤销；身份提供商预配（JIT、SCIM）；暂停
授权——按 MCP 服务器配置 capability 字符串，可授予个人、Group 或 Role
Group 和 Role——共享访问权限，以及手动添加或从身份提供商同步的成员关系
Capability Set——服务器项目组成的命名集合，可作为一个整体进行授权
有效访问权限——按个人或按服务器汇总计算的结果
终端用户自己的连接——服务器要求用户提供凭据时，由每个人提供的凭据

终端用户与 workspace 用户是两种不同的记录。同一个人可以同时拥有这两种记录——此时终端用户记录会显示

hasWorkspaceShare: true

——修改或删除其中一种记录绝不会影响另一种。账户所有者永远不是终端用户：所有者无需记录即可访问所有服务器，不会被列出，也无法被邀请。只有所有者和管理员可以管理终端用户、Group 和 Role。

How to Run the Steps

如何执行这些步骤

This skill names each step by what it reads or changes; the exact calls depend on how you reach the account. Read the one reference that matches your tools -- both follow the step numbers of How to Manage End Users below:

Celigo MCP tools -- references/mcp.md. The deployed server has no end-user, group, role or grant tools, and its user tools cover workspace users only; it can maintain a server's capability sets, so most steps go to the CLI or the integrator.io UI.
The
celigo
CLI -- references/cli.md

Identity-provider setup (JIT sign-in, SCIM, group claims) and suspending an end user happen in the integrator.io UI on either surface.

本 skill 根据每个步骤读取或更改的内容来命名；具体调用取决于进入账户的方式。请阅读与所用工具相匹配的那一份参考文档——两者都遵循下文“如何管理终端用户”中的步骤编号：

Celigo MCP 工具——references/mcp.md。已部署的服务器没有终端用户、Group、Role 或授权工具，其用户工具仅涵盖 workspace 用户；但它可以维护服务器的 Capability Set，因此大多数步骤需要通过 CLI 或 integrator.io UI 完成。
celigo
CLI——references/cli.md

身份提供商配置（JIT 登录、SCIM、Group claims）以及暂停终端用户，无论通过哪种操作界面，都需要在 integrator.io UI 中完成。

How Access Composes

访问权限如何组合

A person can call an item on a server when any of these grants it -- effective access is their union:

Direct grants on the end user's record
Group grants on each group they belong to
Role grants on each role pinned to one of those groups, or listed on the person's own record
Capability sets named by any of those grants

Each grant names one MCP server, or none -- a wildcard across every server in the account -- and lists capabilities:

Capability	Grants on that server
`tool:all` , `tool:<id>`	Tools -- a `tools[]._toolId` , or an upstream tool row's `_id`
`api:all` , `api:<id>`	APIs -- an `apis[]._apiId`
`prompt:all` , `prompt:<id>`	Prompts -- a `prompts[]._id`
`resource:all` , `resource:<id>`	File resources -- a `resources[]._id`
`pset:<id>`	Every member of a capability set -- a `permissionSets[]._id`

Each

:all

covers only its own kind: grant every kind the server exposes. An id that isn't on the server, or any other shape, is refused with 400. Grant prompts as

prompt:<id>

-- an older

tool:<prompt id>

grant still saves but effective access doesn't report it.

End-user grants decide access on servers that sign people in with Celigo OAuth (building-mcp-servers > Who may use the server).

当以下任一授权允许访问时，个人就可以调用服务器上的项目——有效访问权限就是这些授权的并集：

终端用户记录上的直接授权
个人所属每个 Group 上的 Group 授权
固定到这些 Group 或列在个人自己记录上的每个 Role 上的 Role 授权
上述任一授权所指定的 Capability Set

每项授权指定一个 MCP 服务器，或者不指定服务器——不指定时即为账户中所有服务器的通配授权——并列出 capability：

Capability	该服务器上的授权
`tool:all` 、 `tool:<id>`	Tools—— `tools[]._toolId` ，或上游 tool 行的 `_id`
`api:all` 、 `api:<id>`	APIs—— `apis[]._apiId`
`prompt:all` 、 `prompt:<id>`	Prompts—— `prompts[]._id`
`resource:all` 、 `resource:<id>`	File Resources—— `resources[]._id`
`pset:<id>`	Capability Set 的所有成员—— `permissionSets[]._id`

每个

:all

仅涵盖其自身所属类型：授予服务器公开的该类型的所有项目。不在该服务器上的 id，或任何其他格式，都会以 400 错误拒绝。Prompt 应以

prompt:<id>

形式授权——旧式的

tool:<prompt id>

授权仍可保存，但有效访问权限不会报告它。

对于使用 Celigo OAuth 登录的服务器，终端用户授权决定其访问权限（building-mcp-servers > 谁可以使用服务器）。

Quick Reference

快速参考

Decision Matrix

决策矩阵

You need to...	Do this
Give one person access to one server	Invite them with a grant on it, or grant it to their existing record
Give a team access	A group with the grant; add the people as members
Reuse one bundle of access across several groups	A role carrying the grants, pinned to each group
Maintain "which items" on the server, granted as a unit	A capability set on the server, granted as `pset:<id>`
Suspend someone and keep their grants	The UI's toggle on the end user -- no CLI or MCP command
Remove someone's MCP access	Revoke their end-user record
See who can reach a server, and why	The server's effective access
See what one person can reach	That person's effective access

你需要……	执行此操作
授予一个人访问一个服务器的权限	邀请该人员并附带服务器授权，或向其现有记录授予权限
授予一个团队访问权限	创建一个包含该授权的 Group，并将相关人员添加为成员
在多个 Group 之间复用同一组访问权限	创建一个携带这些授权的 Role，并将其固定到每个 Group
维护服务器上“哪些项目”可用，并作为一个整体授权	在服务器上创建 Capability Set，并以 `pset:<id>` 授权
暂停某个人并保留其授权	使用 UI 中终端用户上的开关——没有 CLI 或 MCP 命令
移除某个人对 MCP 的访问权限	撤销其终端用户记录
查看谁可以访问服务器以及原因	查看服务器的有效访问权限
查看某个人可以访问哪些内容	查看该个人的有效访问权限

Record Fields

记录字段

```
_id
```
-- the access-record id (the
```
ashareId
```
every end-user call takes); the person's own user id is
```
_sharedWithUserId
```
```
provisionedBy
```
--
```
invite
```
,
```
jit
```
(first sign-in through the identity provider), or
```
scim
```
(pushed by the identity provider, which then owns the active state and its synced memberships)
```
accepted
```
,
```
dismissed
```
,
```
disabled
```
-- invited until setup completes; declined; suspended

groupMemberships[]

{_groupId, source}

source

being

manual

idp

resourceGrants[]

-- direct grants:

{resourceType: "mcpServer", _resourceId, capabilities}

```
hasWorkspaceShare
```
,
```
lastSignIn
```
-- read-only, joined into the list

```
_id
```
——访问记录 id（每次终端用户调用都使用该
```
ashareId
```
）；个人自己的用户 id 为
```
_sharedWithUserId
```
```
provisionedBy
```
——
```
invite
```
、
```
jit
```
（首次通过身份提供商登录）或
```
scim
```
（由身份提供商推送，此后由其管理活动状态和同步的成员关系）
```
accepted
```
、
```
dismissed
```
、
```
disabled
```
——已邀请但尚未完成设置；已拒绝；已暂停

groupMemberships[]

——

{_groupId, source}

，其中

source

为

manual

或

idp

resourceGrants[]

——直接授权：

{resourceType: "mcpServer", _resourceId, capabilities}

```
hasWorkspaceShare
```
、
```
lastSignIn
```
——只读，合并显示在列表中

Field Reference

字段参考

The full shapes are in the API reference's End Users, Groups and Roles pages (agent-readable markdown).

完整结构请参阅 API 参考中的 End Users、Groups 和 Roles 页面（供 Agent 读取的 Markdown）。

Related Skills

How to Manage End Users

如何管理终端用户

1. Check who has access

1. 检查谁拥有访问权限

List the end users: each row has the access-record id,

provisionedBy

accepted

disabled

and

hasWorkspaceShare

. Workspace-user lists leave end users out, and reading an end user's id through the workspace-user routes answers 404 "AShare not found.". Then list the groups and roles, and read effective access (step 7) for the server or person in question.

列出终端用户：每一行都包含访问记录 id、

provisionedBy

、

accepted

、

disabled

和

hasWorkspaceShare

。workspace 用户列表不包含终端用户；通过 workspace 用户路由读取终端用户的 id 时，会返回 404“AShare not found.”。然后列出 Group 和 Role，并针对相关服务器或个人读取有效访问权限（步骤 7）。

2. Decide how to grant

2. 决定如何授权

Direct grants suit one-offs; groups suit teams; a role suits one bundle reused across groups; a capability set suits a named subset of one server's items that you'd rather maintain on the server than in every grant. Cover every kind of item the server exposes.

直接授权适合一次性需求；Group 适合团队；Role 适合在多个 Group 之间复用同一组授权；Capability Set 适合维护某个服务器项目的命名子集，并将其保留在服务器端，而不是在每项授权中重复维护。必须涵盖服务器公开的所有项目类型。

3. Invite

3. 邀请

Invite one address, or up to 100 at once, optionally adding the same groups and direct grants to each. Every invite sends a real invitation email, so only invite addresses whose owners expect it. The record starts as invited (

accepted: false

) and already counts in effective access; it becomes active when the person completes setup.

An address that already has an end-user record is refused with 409
```
enduser_ashare_exists
```
-- change that record's access instead. A bulk invite answers 200 with a per-address result, so read each one.
The owner's address is refused with 400
```
owner_self_invite_not_allowed
```
.
People can also arrive from the identity provider (
```
jit
```
,
```
scim
```
); that's configured in the UI.

可以邀请一个地址，也可以一次最多邀请 100 个地址，并可选择为每个人添加相同的 Group 和直接授权。每次邀请都会发送真实的邀请邮件，因此只能邀请确实会收到邀请邮件的地址。记录初始状态为已邀请（

accepted: false

），并且已计入有效访问权限；当此人完成设置后，记录才会变为活动状态。

已存在终端用户记录的地址会返回 409
```
enduser_ashare_exists
```
——应改为修改该记录的访问权限。批量邀请会返回 200 及每个地址对应的结果，因此必须逐一读取。
所有者的地址会返回 400
```
owner_self_invite_not_allowed
```
。
人员也可以通过身份提供商进入系统（
```
jit
```
、
```
scim
```
）；相关配置需要在 UI 中完成。

4. Grant access on a server

4. 在服务器上授予访问权限

Granting on a server replaces the listed people's or groups' grant on that server with exactly the capabilities you send -- up to 100 targets per call. Their grants on other servers and their wildcard grants stay. A batch stops at the first failure and reports what it completed, and an id that isn't an end user (or group) of the account rejects the whole call before any change. Send the complete list of capabilities each time; to remove someone's grant on a server altogether, use the UI.

Read effective access afterwards (step 7).

在服务器上授权，会将所列人员或 Group 在该服务器上的授权替换为此次发送的准确 capability，每次调用最多可指定 100 个目标。他们在其他服务器上的授权及通配授权会保留。批量操作遇到第一个失败即停止，并报告已经完成的部分；如果某个 id 不是账户中的终端用户或 Group，则整次调用都会在发生任何更改之前被拒绝。每次都应发送完整的 capability 列表；如需彻底移除某个人在服务器上的授权，请使用 UI。

完成授权后，读取有效访问权限（步骤 7）。

5. Manage groups and roles

5. 管理 Group 和 Role

Group and role names are unique in the account, case-insensitively (409 otherwise).
Members are added and removed by access-record id, up to 100 per call. Adding someone already in the group changes nothing, and the reply's
```
updated
```
counts every listed id either way. Memberships synced from the identity provider (
```
source: idp
```
) can't be removed here (409): change the person's group in the identity provider.
Editing a group or role replaces it. A full update without
```
resourceGrants
```
or
```
_roleIds
```
empties them -- every member loses the access the group gave, while keeping the membership. Read it first and send everything back, or change single fields with a read-modify-write.
Pin roles to groups through the group's
```
_roleIds
```
. An end user's own
```
_roleIds
```
isn't writable through the API.
Deleting a role unpins it from every group; deleting a group removes it from every member's
```
groupMemberships
```
. Neither can be restored from the recycle bin today (Gotchas).

Group 和 Role 名称在账户中必须唯一，且不区分大小写（否则返回 409）。
成员通过访问记录 id 添加和移除，每次调用最多 100 个。添加已经位于 Group 中的人员不会产生变化；无论是否实际发生变更，回复中的
```
updated
```
都会计入每个列出的 id。通过身份提供商同步的成员关系（
```
source: idp
```
）无法在此处移除（返回 409）；应在身份提供商中修改该人员的 Group。
**编辑 Group 或 Role 会替换原对象。**如果完整更新时未提供
```
resourceGrants
```
或
```
_roleIds
```
，这些字段会被清空——每位成员都会失去 Group 提供的访问权限，但成员关系仍会保留。应先读取对象并完整回传，或使用 read-modify-write 方式修改单个字段。
通过 Group 的
```
_roleIds
```
将 Role 固定到 Group。终端用户自己记录上的
```
_roleIds
```
无法通过 API 写入。
删除 Role 会将其从所有 Group 中取消固定；删除 Group 会将其从每位成员的
```
groupMemberships
```
中移除。目前两者都无法从回收站恢复（请参阅“注意事项”）。

6. Grant through capability sets

6. 通过 Capability Set 授权

A capability set lives in the MCP server document (

permissionSets[]

): a

name

unique on the server, case-insensitively, and the ids of items already on the server (

_toolIds

_apiIds

_promptIds

_resourceIds

). Its

_id

is the handle grants use (

pset:<_id>

), and changing its members changes what every grantee can call.

Sets change through a full update of the server, which is where access can shift without a warning:

Removing a set -- leaving it out of the update, or sending it back renamed without its
```
_id
```
-- rewrites every grant that names it into its members' own capabilities (
```
pset:<set>
```
becomes, say,
```
api:<id>
```
). The grantees keep that access, but it no longer follows the set: a set added later, even under the same name, reaches none of them until they're granted it again.
A set sent back without its
_id
keeps its
```
_id
```
and its grants when its name still matches the stored set's (ignoring case).
accessLevel
on a set isn't stored, so it doesn't narrow anything.

Building and updating the server document itself: building-mcp-servers > Gotchas.

Capability Set 位于 MCP 服务器文档中（

permissionSets[]

）：其中包含一个在服务器内唯一且不区分大小写的

name

，以及服务器上已有项目的 id（

_toolIds

、

_apiIds

、

_promptIds

、

_resourceIds

）。其

_id

是授权所使用的标识（

pset:<_id>

）；更改集合成员会更改每位被授权者可以调用的内容。

Capability Set 通过完整更新服务器进行更改，而这也是访问权限可能在没有警告的情况下发生变化的地方：

移除集合——在更新中省略该集合，或将其改名后不再携带
```
_id
```
回传——会将所有引用该集合的授权改写为其成员各自的 capability（例如，
```
pset:<set>
```
会变为
```
api:<id>
```
）。被授权者仍会保留这些访问权限，但权限不再跟随该集合：之后即使以相同名称重新添加集合，也不会自动覆盖这些人，直到再次向他们授权。
回传时缺少
_id
的集合，如果其名称仍与已存储集合的名称匹配（忽略大小写），则会保留原有
```
_id
```
及其授权。
集合上的
```
accessLevel
```
不会被存储，因此不会收窄任何权限。

有关如何构建和更新服务器文档，请参阅 building-mcp-servers > 注意事项。

7. Check effective access

7. 检查有效访问权限

Per server -- every end user who can reach it, with each item's source:
```
direct
```
,
```
group:<name>
```
,
```
role:<name> (group:<name>)
```
, or
```
pset:<set> (direct)
```
/
```
pset:<set> (group:<name>)
```
. An empty result means no end user has been granted the server (the owner is never listed).
Per person -- their groups, roles, and for each server the items they get and the items they're denied, with the reason ("Not in any granted permission set or api grant").

Both are recompiled on every read. Read them after every grant change, and before handing someone a server's URL.

按服务器——列出每位可以访问该服务器的终端用户，以及每个项目的授权来源：
```
direct
```
、
```
group:<name>
```
、
```
role:<name> (group:<name>)
```
，或
```
pset:<set> (direct)
```
/
```
pset:<set> (group:<name>)
```
。结果为空表示没有终端用户被授予该服务器（所有者永远不会被列出）。
按个人——列出其 Group、Role，并针对每个服务器列出其获得和被拒绝的项目以及原因（“Not in any granted permission set or api grant”）。

两种结果都会在每次读取时重新汇总计算。每次更改授权后都应重新读取，并在将服务器 URL 提供给任何人之前进行确认。

8. Suspend, revoke, or offboard

8. 暂停、撤销或办理离职

Suspend with the UI's toggle on the end user: access stops and the record, groups and grants stay. There's no CLI or MCP command for it -- the workspace-user disable commands can't find an end-user record.
Revoke to remove the person's MCP access: the record is deleted with its group memberships, the person's own connections for MCP servers are invalidated, and any workspace record they hold is untouched. Inviting the address again creates a fresh record with none of the old grants or groups.
A
scim
record is the identity provider's: deactivate the person or change their groups there, or its next push undoes a change made here. Direct grants and manual memberships are never touched by SCIM.
Offboarding someone with both kinds of access means revoking the end-user record and removing the workspace user (managing-users > 5. Disable or remove a user).

暂停：使用 UI 中终端用户上的开关。访问会立即停止，但记录、Group 和授权都会保留。没有对应的 CLI 或 MCP 命令——workspace 用户的禁用命令无法找到终端用户记录。
撤销：用于移除个人的 MCP 访问权限。记录及其 Group 成员关系会被删除，个人针对 MCP 服务器创建的连接会失效，而其持有的 workspace 记录不会受到影响。再次邀请同一地址会创建一条全新记录，不包含任何旧授权或 Group。
scim
记录归身份提供商所有：应在身份提供商中停用该人员或修改其 Group，否则身份提供商的下一次推送会撤销此处所做的更改。SCIM 永远不会影响直接授权和手动成员关系。
办理离职：如果此人同时拥有两种访问权限，需要撤销终端用户记录并移除 workspace 用户（managing-users > 5. 禁用或移除用户）。

9. Manage end users' own connections

9. 管理终端用户自己的连接

Where a server requires end-user credentials on a connection, each end user's credentials live in a private copy of it (

connectionRole: mcpChild

) -- see building-mcp-servers > Whose login a call uses. The copies are listed per server and read one at a time, credentials masked. Deleting one makes that person connect again before using the tools that need it; a deleted copy can't be restored, and only the end-user connection route deletes one.

当服务器要求在某个连接上使用终端用户凭据时，每个终端用户的凭据都保存在该连接的私有副本中（

connectionRole: mcpChild

）——请参阅 building-mcp-servers > 调用使用谁的登录身份。这些副本按服务器列出，并且每次只能读取一个，凭据会被隐藏。删除某个副本后，该人员在再次使用需要该凭据的 Tools 前必须重新连接；已删除的副本无法恢复，而且只有终端用户连接路由可以删除副本。