应用服务
组织
让应用的终端用户自己组建团队: 创建组织、邀请成员、分配角色、转让与解散。组织只属于一个应用,不跨应用;成员关系、邀请、席位与组织动态由 CZL Connect 维护,接入方按令牌或应用级 API 读取。
组织与应用的「团队成员」是两回事:团队成员是帮你管理应用的协作者 (管理员、客服),组织是应用的用户之间的团队 (比如一家外贸公司的 5 个人共用一套单据)。
适用场景
- 桌面端 / 移动端要做「团队版」,但不想自建服务端维护成员与邀请
- 有服务端的应用要按团队计费或共享额度,需要可靠的成员关系
- 配合 CZL Connect 的数据同步,让团队成员共享一个数据空间
开通条件
组织按应用所有者的套餐开放,额度为每个应用可建的组织数:
| 套餐 | 每应用组织数 |
|---|---|
| Lite | 不支持 |
| Plus | 500 |
| Pro | 5,000 |
| Enterprise | 不限 |
达到上限后用户无法新建组织,已有组织照常使用。
应用中开通
进入应用详情 → 组织:
| 设置 | 说明 |
|---|---|
| 开通组织 | 关闭后不能新建组织、不能邀请,已有组织与成员保留 |
| 每个组织的席位 | 1 ~ 500,席位 = 成员数 + 未过期的邮箱邀请数 |
| 每人可拥有的组织数 | 至少 1。设为 1 即「一人只能是一个组织的所有者」 |
| 每人可加入的组织数 | 含自己拥有的,不少于可拥有数。设为 1 即「一人只能属于一个组织」 |
调低上限不影响已有关系,只约束之后的创建、加入与转让。同一页可以按名称搜索应用下的全部组织。
角色
| 角色 | 能做的事 |
|---|---|
owner 所有者 | 全部操作,唯一,可转让给其他成员 (原所有者降为管理员),可解散组织,不能退出 |
admin 管理员 | 改名、邀请 (邮箱 / 邀请码)、撤回邀请、管理成员与只读成员 |
member 成员 | 查看成员与动态、退出 |
viewer 只读成员 | 同成员;接入方据此限制写入 (如数据同步只读) |
只能管理比自己级别低的成员,只能授予比自己低的角色。组织所有者被全局封禁时组织转为只读 (status: readonly),不能邀请与加入,解封后恢复。
邀请
两种方式,都需要 admin 以上:
- 邮箱邀请:不论邮箱是否注册都返回同样结果,对方在 CZL Connect 的通知中心接受,同时收到邮件;7 天有效,拒绝后 7 天内不能再邀请同一邮箱
- 邀请码:12 位字符,可设可用次数 (默认 1,上限为席位数) 与有效期 (默认 7 天,最长 30 天)。明文只在生成时返回一次,同时返回托管加入页
https://connect.czl.net/orgs/join?code=XXXX;也可以自己包装成 App 的自定义协议链接 (如myapp://team/join?code=XXXX),在 App 里调用加入接口
接受邀请或凭码加入时会再次校验席位与「每人可加入的组织数」。应用开启了「仅受邀用户」时,加入组织即视同进入受邀名单。
用户令牌接口
客户端用 OAuth2 访问令牌直接调用,只能看到令牌所在应用的组织。基址:https://connect.czl.net/api/oauth2/orgs,请求头 Authorization: Bearer <access_token>。
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `` | 我在本应用的组织 → {items: [Org]} |
| POST | `` | 创建组织 {name} → Org,创建人为所有者 |
| POST | /join | 凭邀请码加入 {code} → {org: Org, alreadyMember} |
| GET | /{orgId} | 组织详情:Org + members;admin 以上另含 invites、inviteCodes |
| PATCH | /{orgId} | 改名 {name} |
| DELETE | /{orgId} | 解散 (所有者) |
| POST | /{orgId}/transfer | 转让 {memberId} (所有者) |
| POST | /{orgId}/leave | 退出 |
| POST | /{orgId}/invites | 邮箱邀请 {email, role} |
| DELETE | /{orgId}/invites/{inviteId} | 撤回邮箱邀请 |
| POST | /{orgId}/invite-codes | 生成邀请码 {role, maxUses, ttlDays} → 含 code、joinUrl |
| DELETE | /{orgId}/invite-codes/{codeId} | 撤回邀请码 |
| PUT | /{orgId}/members/{memberId} | 改角色 {role} |
| DELETE | /{orgId}/members/{memberId} | 移除成员 |
| GET | /{orgId}/activity?before=&limit= | 组织动态,新的在前;before 传上一页最后一条的 createdAt |
Org 结构:
{
"id": "0193b6a0-…",
"name": "华东外贸部",
"status": "active",
"role": "owner",
"memberCount": 3,
"seats": 5,
"createdAt": "2026-11-20T08:00:00Z"
}成员条目:{id, name, avatar, email, role, joinedAt, isSelf},email 为打码形式。组织动态条目:{action, actor, actorAvatar, target, params, description, createdAt},action 取值 create / update / invite_member / revoke_invite / accept_invite / decline_invite / update_member / remove_member / leave_org / transfer_owner / delete,params.via 为 email 或 code。
错误统一为 {error: "..."}:不是成员或组织不存在 404,角色不够或应用未开通 403,其余校验失败 400。
托管页面
没有自建界面的接入方可以直接在系统浏览器里打开 CZL Connect 的页面,用户用 CZL Connect 账号登录后管理:
https://connect.czl.net/orgs:我加入的全部组织https://connect.czl.net/orgs/{orgId}:成员、邀请、邀请码、动态https://connect.czl.net/orgs/join?code=XXXX:凭邀请码加入
应用级 API
有服务端的接入方用 API key (czlc_live_…,勾选 org:read) 读取,详见 应用级 API:
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/v1/app/orgs?page=&pageSize=&keyword= | 应用下的组织 → {items: [{id, name, status, memberCount, owner, createdAt}], total},owner 为用户标识 |
| GET | /api/v1/app/orgs/{orgId}/members | 成员 → {items: [{userId, role, joinedAt}]} |
| GET | /api/v1/app/users/{userId}/orgs | 用户所属组织 → {items: [{id, name, role}]} |
userId 与 OIDC sub 同一个值。
通知
被邀请、被移出、角色变更、成为所有者、组织解散都会写入当事人的 CZL Connect 通知中心;邮箱邀请另发一封邮件。所有组织操作都记入应用的操作日志,并出现在组织动态里。