Skip to content

Reference

What this page is

Look-up facts for Zitadel: versions and support windows, licensing by path, Zitadel Cloud pricing and SLA, requirements, API and endpoint paths, configuration keys, built-in roles, enums, database schema, recent security advisories, and a hardening checklist. Explanations of why live in Explanation; step-by-step tasks live in How-to Guides. Facts verified 2026-09-25 against the zitadel/zitadel repository (docs sources under apps/docs/content/, cmd/defaults.yaml, proto/) and GitHub releases.

Versions and Support

Line Latest release First GA Status (2026-09-25)
v5 / "next iteration" none released roadmap: production rollout 2027 Preview only ("instant authentication" preview); no v5 tag exists
v4.x v4.19.1 (2026-09-23) v4.0.0 (2025-07-31) Current. Supported for at least 12 months per the roadmap
v3.x v3.4.15 (2026-08-14) v3.0.0 (2025-05-02) End of life: the 2026-09-24 advisory GHSA-4hgj-wm6c-q7p2 states the 3.x line "reached end-of-life and will not receive patches"
v2.x n/a n/a End of life (roadmap). CockroachDB support in v2 was maintenance-only until 2025-09-30

Skip v4.18.0

v4.18.0 (2026-09-21) has a failing setup step; the release notes and advisories say to go straight to v4.19.0 or later. v4.19.1 is the patched release for GHSA-4hgj-wm6c-q7p2.

Recent v4 releases (from GitHub releases):

Version Date Note
v4.19.1 2026-09-23 Latest; fixes Login V1 unauthenticated rename (GHSA-4hgj-wm6c-q7p2)
v4.19.0 2026-09-23 Eventstore unique-constraint fixes
v4.18.0 2026-09-21 Do not use (setup step fails)
v4.17.3 2026-09-04 Fixes critical IdP manual-linking takeover (GHSA-g8gj-gq47-xgf4)
v4.17.0 2026-08-12
v4.16.2 2026-07-29
v4.15.0 2026-05-04 Release date per releasealert.dev listing
v4.11.0 TBD Minimum version for PostgreSQL 18 (date not checked)
v4.0.0 2025-07-31 Login V2 default for new instances, Actions V2 GA, resource-based v2 APIs, Service Ping

Release cadence: v4 shipped 19 minor versions in about 14 months (roughly monthly), with patch releases in between. Zitadel uses semantic versioning; breaking changes only in a new major.

Licensing by Path

From LICENSING.md in zitadel/zitadel (checked 2026-09-25):

Path License
Repository default (core Go backend, Management Console) AGPL-3.0-only
proto/ (API definitions), apps/docs/ Apache-2.0
apps/login/ (Login V2, Next.js), packages/zitadel-client/, packages/zitadel-proto/ MIT
Community contributions Must be licensed Apache-2.0 (no CLA)
Separate SDK repos (for example zitadel-go, client-python 4.1.9 on PyPI) Apache-2.0 per their package metadata
npm @zitadel/react 1.1.1, @zitadel/proto 1.3.1, @zitadel/client 1.3.1 MIT
npm @zitadel/node 3.0.28 Apache-2.0

License history

Zitadel moved from Apache-2.0 to AGPL-3.0 with v3 (announced March 2025, v3.0.0 released 2025-05-02). The v3 announcement listed the Hosted Login as AGPL; the current LICENSING.md lists apps/login/ as MIT. A commercial license is available on request.

Zitadel Cloud Pricing and SLA

Item Value Source
Free plan $0; 100 daily active users (DAU), unlimited total users, 3 external IdPs zitadel.com/pricing via search snippets, 2026-09
Pro plan $100/month base, includes 25,000 DAU, then usage-based Zitadel help center and pricing page snippets, 2026-09
Enterprise Custom annual contract; recommended above 175,000 DAU or 150 active external IdPs Zitadel help center snippet, 2026-09
Extended Support and SLA add-on $999/month Pricing page snippet, 2026-09
Data location add-on Available; price TBD (not confirmed from an official page in this review) Pricing page snippet
Regions US, EU, AU, CH README.md
Default uptime SLA 99.50% legal/service-description/service-level-description.mdx
Extended SLA 99.95% same

Service credits by achieved uptime (from the service level description): below the guaranteed level, credits of 10%, 25%, or 50% apply depending on how far availability fell.

Requirements

Component Requirement Source
Database PostgreSQL 14 to 18 (18 requires Zitadel v4.11.0+). Only supported database since v3 self-hosting/manage/requirements.mdx, Kubernetes guide
CockroachDB Removed in v3.0.0; migrate with zitadel mirror v3.0.0 release notes
Cache (optional) Redis in standalone mode (no Cluster or Sentinel); or PostgreSQL unlogged tables; or in-memory self-hosting/manage/cache.mdx
Kubernetes 1.30+ (kubeVersion: '>= 1.30.0-0' in the chart) Helm chart Chart.yaml
Helm 3.x or 4.x Kubernetes guide
Docker Compose Compose v2 (V1 docker-compose unsupported); Docker Engine 24+, 2 GB RAM for the compose stack compose guide
Reverse proxy Any proxy with HTTP/2 upstream (h2c or h2). Tested: Traefik v3, NGINX 1.x, Caddy 2, Apache httpd 2.4 requirements page
Resources Zitadel about 512 MB RAM, under 1 core; database about 1 core per 100 req/s and 4 GB RAM per core; plan 4 cores for password hashing spikes production guide
Minimal HA 3 nodes x 4 CPU / 16 GB (or 4 CPU / 8 GB without log and metric collectors) production guide
Build toolchain Go 1.25 (go.mod) repository

Container Images and Charts

Artifact Name
API server image ghcr.io/zitadel/zitadel:<version>
Login V2 image ghcr.io/zitadel/zitadel-login:<version> (same version tag as the API)
Helm repo https://charts.zitadel.com, chart zitadel/zitadel (chart 10.0.6 at check time, optional Bitnami PostgreSQL subchart for quickstarts)
Compose pack deploy/compose/docker-compose.yml + .env.example in zitadel/zitadel (Traefik, API, Login, PostgreSQL; optional Redis and OTel collector profiles)
Terraform provider zitadel/zitadel, v3.8.7 (2026-09-25)
Go SDK github.com/zitadel/zitadel-go/v3

HTTP Paths and Ports

Path Serves
:8080 Default listen port of the API binary (Port, ZITADEL_PORT)
:3000 Login V2 container port
/ui/console/ Management Console (Angular)
/ui/v2/login Login V2 (Next.js, separate container)
/ui/login/ Login V1 (legacy, built into the binary)
/v2/ v2 REST (HTTP/JSON transcoding)
/zitadel.<service>.v2.<Service>/ v2 gRPC and Connect RPC
/v2beta/ Backward-compatible beta paths
/auth/v1/, /management/v1/, /admin/v1/, /system/v1/, /assets/v1/ Legacy v1 REST
/oauth/v2/, /oidc/v1/, /saml/v2/ Standards endpoints
/.well-known/openid-configuration OIDC discovery
/debug/healthz Liveness (used by the Helm chart)
/debug/ready Readiness and startup (checks database connectivity)
/debug/metrics Metrics endpoint (legacy Metrics section)
/ui/v2/login/healthy, /ui/v2/login/ready Login V2 liveness and readiness

OIDC and OAuth Endpoints

Endpoint Path
Authorization /oauth/v2/authorize
Token /oauth/v2/token
Introspection /oauth/v2/introspect
Userinfo /oidc/v1/userinfo
Revocation /oauth/v2/revoke
End session /oidc/v1/end_session
JWKS /oauth/v2/keys
Dynamic client registration (RFC 7591/7592) /oauth/v2/register (when enabled in instance security settings)
Device authorization Advertised in the discovery document; user-facing page at /device

Token endpoint grants: authorization code (with PKCE), refresh token, JWT profile (RFC 7523), client credentials, token exchange (RFC 8693), device code. The resource owner password grant is not offered.

API Services

v2 is the recommended surface for new work; v1 is fully supported but no longer extended.

v2 service REST prefix Notes
zitadel.user.v2.UserService /v2/users POST /v2/users/new (CreateUser, human or machine), POST /v2/users/human, PATs at /v2/users/{id}/pats, keys, secrets, metadata, passkeys
zitadel.session.v2.SessionService /v2/sessions POST create, PATCH /v2/sessions/{id} set checks, DELETE, POST /v2/sessions/search
zitadel.org.v2.OrganizationService /v2/organizations Create, update, _search, domains, metadata
zitadel.action.v2.ActionService /v2/actions Targets (/v2/actions/targets), executions (PUT /v2/actions/executions)
zitadel.webkey.v2.WebKeyService /v2/web_keys OIDC signing keys
zitadel.oidc.v2.OIDCService /v2/oidc Auth requests and callbacks for custom login UIs, device authorization
zitadel.saml.v2.SAMLService Connect/gRPC SAML requests and responses for custom login UIs
zitadel.project.v2.ProjectService Connect/gRPC only (no REST annotation in proto) Projects, roles, project grants
zitadel.application.v2.ApplicationService Connect/gRPC only OIDC, SAML, API apps, keys, secrets
zitadel.authorization.v2.AuthorizationService Connect/gRPC User authorizations (grants)
zitadel.instance.v2.InstanceService Connect/gRPC Instance management
zitadel.idp.v2, zitadel.group.v2, zitadel.settings.v2, zitadel.feature.v2 mixed IdPs, user groups, settings, feature flags

Legacy v1: AuthService (current user), ManagementService (organization scope), AdminService (instance scope), SystemService (multi-instance, self-hosted system users), Assets API. SCIM 2.0 is served per organization at /scim/v2/{orgId}/ (Users resource: create, get, list, replace, patch, delete).

Configuration Keys

From cmd/defaults.yaml (every key has an env var ZITADEL_<PATH>):

Key Default Meaning
Port 8080 Listen port
ExternalDomain localhost Public domain; issuer and instance lookup. Applied during setup
ExternalPort 8080 Public port
ExternalSecure true Whether the public URL is HTTPS
TLS.Enabled (per --tlsMode) TLS on the Zitadel listener itself
Database.postgres.DSN empty Full PostgreSQL URL; when set, host/user fields are ignored
Caches.Connectors.{Memory,Postgres,Redis}.Enabled false, true, false Cache backends
Caches.{Instance,Milestones,Organization}.Connector empty (no cache) Which backend each object cache uses
Instrumentation.Trace.Exporter.Type none none, auto, stdOut, stdErr, grpc, http, google
Instrumentation.Metric.Exporter.Type none Same plus prometheus
Instrumentation.Log.Level INFO Log level
Tracing, Metrics none, otel Deprecated in favor of Instrumentation
Telemetry.Enabled false Milestone push to external endpoints
ServicePing.Enabled true Anonymized usage reports to zitadel.com (daily); opt out with false
SystemDefaults.PasswordHasher.Hasher.Algorithm bcrypt (cost 14) Also argon2i, argon2id, scrypt, pbkdf2, sha2
AuditLogRetention 0s Audit log retention (0 = unlimited)
LogStore.Access.Stdout.Enabled false Access log to stdout
Environment variable Purpose
ZITADEL_MASTERKEY / --masterkey Exactly 32 characters; AES-256 key for secrets at rest. Cannot be changed after init
ZITADEL_DATABASE_POSTGRES_DSN Database connection
ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORD Initial admin password (first start only; default Password1!)
ZITADEL_FIRSTINSTANCE_LOGINCLIENTPATPATH Where setup writes the Login V2 service-user PAT
ZITADEL_DEFAULTINSTANCE_FEATURES_LOGINV2_REQUIRED Make new instances use Login V2

CLI phases: zitadel init (once; zitadel init schema for managed PostgreSQL), zitadel setup (every version; --init-projections), zitadel start; combined start-from-init, start-from-setup; zitadel mirror for database-to-database copy; zitadel ready for health checks. --tlsMode is disabled, external, or enabled.

Built-in Administrator Roles

Scope Roles (from InternalAuthZ in defaults.yaml)
System SYSTEM_OWNER, SYSTEM_OWNER_VIEWER
Instance (IAM) IAM_OWNER, IAM_OWNER_VIEWER, IAM_ORG_MANAGER, IAM_USER_MANAGER, IAM_LOGIN_CLIENT, IAM_ADMIN_IMPERSONATOR, IAM_END_USER_IMPERSONATOR
Organization ORG_OWNER, ORG_OWNER_VIEWER, ORG_USER_MANAGER, ORG_USER_PERMISSION_EDITOR, ORG_USER_SELF_MANAGER, ORG_PROJECT_CREATOR, ORG_PROJECT_PERMISSION_EDITOR, ORG_SETTINGS_MANAGER, ORG_DYNAMIC_CLIENT_REGISTRAR, ORG_ADMIN_IMPERSONATOR, ORG_END_USER_IMPERSONATOR
Project PROJECT_OWNER, PROJECT_OWNER_VIEWER, PROJECT_OWNER_GLOBAL, PROJECT_OWNER_VIEWER_GLOBAL
Project grant PROJECT_GRANT_OWNER, PROJECT_GRANT_OWNER_VIEWER
Self SELF_MANAGEMENT_GLOBAL

OIDC Application Enums

Field Values
Application type OIDC_APP_TYPE_WEB, OIDC_APP_TYPE_USER_AGENT, OIDC_APP_TYPE_NATIVE
Auth method OIDC_AUTH_METHOD_TYPE_BASIC, _POST, _NONE (public client, use PKCE), _PRIVATE_KEY_JWT
Grant types OIDC_GRANT_TYPE_AUTHORIZATION_CODE, _IMPLICIT, _REFRESH_TOKEN, _DEVICE_CODE, _TOKEN_EXCHANGE
Response types OIDC_RESPONSE_TYPE_CODE, _ID_TOKEN, _ID_TOKEN_TOKEN
Access token type Bearer (opaque) or JWT

Authentication Factors and Hashes

Category Supported
Protocols OpenID Connect (certified OP), OAuth 2.0, SAML 2.0 IdP, LDAP (as IdP), SCIM 2.0 server
Passwordless Passkeys (FIDO2/WebAuthn)
Second factors TOTP (authenticator app), U2F security keys, OTP via email, OTP via SMS
Machine auth JWT profile (private key JWT), personal access tokens, client credentials
Password hashing bcrypt (default), argon2i/argon2id (disabled on Zitadel Cloud), scrypt, pbkdf2, sha2; import-only verifiers for md5 variants, phpass, drupal7
Secrets at rest AES-256 with the masterkey

Database Schema

Schema Contents
eventstore events2 (the event log), unique constraints, sequences, push function
projections Read models (projections.users, orgs, projects, ...), current_sequences, failed_events
system Assets, encryption keys
auth, adminapi, notification Older projection schemas being migrated into projections
cache schema PostgreSQL cache connector (unlogged tables)

eventstore.events2 columns: instance_id, aggregate_type, aggregate_id, event_type, sequence, revision, created_at, payload, creator, owner, position, in_tx_order. Primary key (instance_id, aggregate_type, aggregate_id, sequence).

Security Advisories (2026)

Selected advisories from github.com/zitadel/zitadel/security/advisories:

GHSA Severity Published Summary Fixed in
GHSA-4hgj-wm6c-q7p2 High (8.2) 2026-09-24 Unauthenticated rename of any user via Login V1 v4.19.1 (3.x not patched)
GHSA-g8gj-gq47-xgf4 Critical (9.8) 2026-09-04 Account takeover via external IdP manual linking (Login V2, AddIDPLink) v4.17.3
GHSA-jh3m-cr2x-qp88 High 2026-09-04 Session hijacking via forgeable IdP intent tokens see advisory
GHSA-j344-gqv4-84ff Moderate 2026-09-04 Cross-organization authentication method enumeration see advisory
GHSA-pq2q-2c6r-75c4 Critical 2026-08-14 Cross-org takeover via passkey/passwordless enrollment codes see advisory
GHSA-3gwm-5wx8-4gm6 High 2026-08-14 Takeover via OTP-Email/SMS return-code bypass in Login V2 see advisory
GHSA-558c-v5wc-9w4q High 2026-08-14 Users of deactivated orgs can log in via Login V2 see advisory
GHSA-45f2-5q3r-xgg6 Critical 2026-07-29 Takeover via passkey enrollment on Login V1 and V2 see advisory
GHSA-93hm-8q29-c8cr Low 2026-07-29 SSRF in organization domain HTTP verification see advisory

Hardening Checklist

  • Run the latest v4 patch (v3 no longer receives fixes); subscribe to GitHub security advisories.
  • Generate a random 32-character masterkey before first start and store it in a secret manager; it cannot be rotated in place.
  • Change the initial admin password (Password1! default) or set it before first start.
  • Use a non-superuser database role in the runtime DSN and sslmode=verify-full for remote PostgreSQL.
  • Terminate TLS and forward HTTP/2 (h2c) to the API; set ExternalDomain, ExternalPort, ExternalSecure to match the public URL.
  • Enforce MFA or passkeys in the login policy; review lockout and password complexity policies.
  • Prefer JWT profile over client secrets for service accounts; give PATs an expiration date.
  • Migrate Actions V1 (embedded JavaScript) to Actions V2 targets; verify the ZITADEL-Signature header in target endpoints.
  • Add rate limiting and bot detection in front of Zitadel (production guide recommendation).
  • Decide on Service Ping (ServicePing.Enabled) for your data-sharing policy.
  • Back up PostgreSQL before every zitadel setup run.

Sources