Skip to content

Changelog

2026-08-07

Documentation audit — organization, workspace, and a new teams page

Reconciled Organizations and Workspaces against the current code and added a new Teams page, all with updated OpenAPI specs. A lot landed since the last pass:

Org creation & hosting - Org creation now takes hosting_type (cloud/on_prem) and a required company_code; on_prem orgs skip app-access and admin-user creation entirely and get a license key back instead. company_code/hosting_type/license keys are owned by AuthAPI, not stored locally — CoreAPI just proxies them through. - Added a platform-admin org list endpoint and an org status (approve/disable) endpoint.

Self-signup - New public self-signup flow: an applicant verifies their email (6-digit code), then applies — no Zitadel org or local admin user is created until a platform admin approves. Approval generates a temporary password, creates the admin, creates the org's Default workspace, and emails the admin their login details.

Roles & permissions - PATCH .../users/:userId/role now accepts custom org-scoped roles, not just the five system roles. - Custom roles can now be updated and deleted (previously create/list only), and a role's current members can be listed. - Platform-scope roles are no longer returned by the org-scoped role endpoints. - Added a live permissions-catalog endpoint listing every permission string by scope, so client code doesn't need to hand-maintain its own copy. - Permission names are now consistently namespaced (e.g. org:users:manage, platform:org:create) — several endpoints' required permission changed name (not behavior) as part of this.

Default workspace - Every org now gets a Default workspace auto-created — right after admin-user creation for direct org creation, or on approval for a self-signup org. Not skippable; documented in Workspaces.

Teams (new) - Org-scoped teams that can be granted a role on a workspace as a unit, instead of adding every member individually. Full CRUD for teams, team membership, and team-to-workspace role grants, with write-time checks preventing a user from having both direct and team-based access to the same workspace. See the new Teams page.

Corrections - The JWT role claim documentation was stale — AuthAPI moved from an orgs[] array to a single org: {org_id, org_slug, role} object a while ago; the internal role-lookup endpoint doc now reflects that (and notes it only supports one org per user, LIMIT 1, no org_id filter).

2026-07-22

Added Organizations and Workspaces pages — tenant creation, membership, roles, app access, spaces/channels — with their own OpenAPI specs; updated the domain overview to distinguish the legacy ticketing general settings from the platform org/workspace hierarchy

2026-06-23

Initial tenancy domain documentation