App services
Organizations
On this page
Lets your app's end users form their own teams: create organizations, invite members, assign roles, transfer ownership and dissolve. An organization belongs to exactly one app and never spans apps. CZL Connect maintains memberships, invitations, seats and organization activity; you read them with user tokens or the app-level API.
Organizations are not the same as your app's "team members". Team members are collaborators who help you run the app (admins, support agents); organizations are teams formed by the app's users (for example, five people at a trading company sharing one set of documents).
Use cases
- A desktop or mobile app wants a "team edition" without running its own server for members and invitations
- An app with its own backend bills or shares quota per team and needs reliable memberships
- Combined with CZL Connect data sync, team members share one data space
Requirements
Organizations are available based on the app owner's plan. The quota is the number of organizations each app can have:
| Plan | Organizations per app |
|---|---|
| Lite | Not supported |
| Plus | 500 |
| Pro | 5,000 |
| Enterprise | Unlimited |
Once the limit is reached, users cannot create new organizations; existing ones keep working.
Enabling for an app
Open the app details → Organizations:
| Setting | Description |
|---|---|
| Enable organizations | When off, no new organizations or invitations; existing organizations and members are kept |
| Seats per organization | 1 – 500. Seats = members + unexpired email invitations |
| Organizations a user can own | At least 1. Set to 1 for "a user can own only one organization" |
| Organizations a user can join | Including owned ones, no less than the ownership limit. Set to 1 for "a user can belong to only one organization" |
Lowering a limit does not affect existing memberships; it only constrains later creation, joining and transfers. The same page lets you search all organizations in the app by name.
Roles
| Role | Permissions |
|---|---|
owner | Everything. Unique; can transfer ownership to another member (the previous owner becomes an admin) and dissolve the organization; cannot leave |
admin | Rename, invite (email / invitation code), revoke invitations, manage members and read-only members |
member | View members and activity, leave |
viewer | Same as member; your app uses it to restrict writes (for example, read-only sync) |
You can only manage members ranked below you and only grant roles below your own. If the organization owner is globally banned, the organization becomes read-only (status: readonly): no invitations or joins until the ban is lifted.
Invitations
Two ways, both requiring admin or above:
- Email invitation: returns the same result whether or not the email is registered. The invitee accepts in the CZL Connect notification center and also receives an email. Valid for 7 days; after a decline, the same email cannot be invited again for 7 days
- Invitation code: 12 characters, with a configurable number of uses (default 1, up to the seat count) and validity (default 7 days, up to 30). The plain code is returned only once, together with the hosted join page
https://connect.czl.net/orgs/join?code=XXXX. You can also wrap it in your app's custom scheme (such asmyapp://team/join?code=XXXX) and call the join endpoint from your app
Seats and the per-user join limit are checked again when an invitation is accepted or a code is redeemed. If the app is invite-only, joining an organization also adds the user to the invited-users list.
User token endpoints
Clients call these directly with an OAuth2 access token and only see organizations in the token's app. Base URL: https://connect.czl.net/api/oauth2/orgs, header Authorization: Bearer <access_token>.
| Method | Path | Description |
|---|---|---|
| GET | `` | My organizations in this app → {items: [Org]} |
| POST | `` | Create {name} → Org; the creator becomes owner |
| POST | /join | Redeem an invitation code {code} → {org: Org, alreadyMember} |
| GET | /{orgId} | Details: Org + members; admin and above also get invites and inviteCodes |
| PATCH | /{orgId} | Rename {name} |
| DELETE | /{orgId} | Dissolve (owner) |
| POST | /{orgId}/transfer | Transfer {memberId} (owner) |
| POST | /{orgId}/leave | Leave |
| POST | /{orgId}/invites | Email invitation {email, role} |
| DELETE | /{orgId}/invites/{inviteId} | Revoke an email invitation |
| POST | /{orgId}/invite-codes | Generate a code {role, maxUses, ttlDays} → includes code and joinUrl |
| DELETE | /{orgId}/invite-codes/{codeId} | Revoke a code |
| PUT | /{orgId}/members/{memberId} | Change role {role} |
| DELETE | /{orgId}/members/{memberId} | Remove a member |
| GET | /{orgId}/activity?before=&limit= | Activity, newest first; pass the last item's createdAt as before for the next page |
Org shape:
{
"id": "0193b6a0-…",
"name": "East China Sales",
"status": "active",
"role": "owner",
"memberCount": 3,
"seats": 5,
"createdAt": "2026-11-20T08:00:00Z"
}Member item: {id, name, avatar, email, role, joinedAt, isSelf}, with email masked. Activity item: {action, actor, actorAvatar, target, params, description, createdAt}, where action is one of create / update / invite_member / revoke_invite / accept_invite / decline_invite / update_member / remove_member / leave_org / transfer_owner / delete, and params.via is email or code.
Errors are {error: "..."}: 404 when you are not a member or the organization does not exist, 403 when your role is insufficient or the app has not enabled organizations, 400 for other validation failures.
Hosted pages
Apps without their own UI can open CZL Connect pages in the system browser; users sign in with their CZL Connect account to manage:
https://connect.czl.net/orgs: all my organizationshttps://connect.czl.net/orgs/{orgId}: members, invitations, codes, activityhttps://connect.czl.net/orgs/join?code=XXXX: redeem an invitation code
App-level API
Apps with a backend read these with an API key (czlc_live_… with org:read). See App API:
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/app/orgs?page=&pageSize=&keyword= | Organizations in the app → {items: [{id, name, status, memberCount, owner, createdAt}], total}, where owner is a user identifier |
| GET | /api/v1/app/orgs/{orgId}/members | Members → {items: [{userId, role, joinedAt}]} |
| GET | /api/v1/app/users/{userId}/orgs | A user's organizations → {items: [{id, name, role}]} |
userId is the same value as the OIDC sub.
Notifications
Invitations, removals, role changes, becoming owner and dissolution are written to the affected user's CZL Connect notification center; email invitations also send an email. Every organization action is recorded in the app's audit log and shown in the organization activity.