# Organizations 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 as `myapp://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 `. | 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: ```json { "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 organizations - `https://connect.czl.net/orgs/{orgId}`: members, invitations, codes, activity - `https://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](/docs/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.