README
¶
Zitadel — next generation
The next generation of the Zitadel identity platform, built for developers and AI agents alike: registration and login live in your app, under your brand, while Zitadel guards the credentials, sessions, and tokens underneath.
Preview status: This work rebuilds Zitadel's storage core and API surface, so it ships as a preview in its own repository and is intended to merge back into zitadel/zitadel as the foundation of a future major version. APIs, CLI flags, package surfaces, and docs are still in flux. Create-first, claim-later is the product direction, and
zitadel claimships in this repo (ADR 046). The full story is in VISION.md.
Workflow front doors
I am contributing to Zitadel
See CONTRIBUTING.md for contributor setup (including the devcontainer), Moon commands, local checks, integration tests, source builds, and release workflows. Agent-facing workspace rules live in AGENTS.md.
I am adding Zitadel to my app
| I want to... | Run |
|---|---|
| Check local runtime prerequisites | npx @zitadel/cli@alpha doctor |
| Start local Zitadel | npx @zitadel/cli@alpha start |
| Add auth to my app | npx @zitadel/cli@alpha setup --server local |
| Check generated app files | npx @zitadel/cli@alpha doctor |
| Stop local Zitadel, keeping data | npx @zitadel/cli@alpha stop |
| Delete local Zitadel data | npx @zitadel/cli@alpha reset --force |
The published zitadel runtime commands run the released local runtime through
the @zitadel/server npm binary by default and do not require Docker, Go, Moon,
or a source checkout. Docker remains available with
zitadel start --runtime docker.
I am an agent (or driving one)
The CLI is the agent-facing surface today: every command supports
--non-interactive --json and returns a structured envelope.
apps/cli/SKILLS.md is the canonical contract for agents
integrating Zitadel into an app; AGENTS.md is for agents
contributing to this repository. The documentation site publishes LLM-friendly
text at /llms.txt, /llms-full.txt, and page-level .md URLs.
Customer quick start
mkdir myapp
cd myapp
npx @zitadel/cli@alpha doctor
Pick a server before running setup — it can't be changed on this app
afterward. Use --server local for local dev, or point at a hosted Zitadel
Cloud instance if you intend to claim the project later and attach it to your
team:
npx @zitadel/cli@alpha start # local dev only
npx @zitadel/cli@alpha setup --server local # or --server https://api.zitadel.cloud
npm run dev
Open http://localhost:3000/login and register your first user. setup walks
through the scaffold choices (such as which framework and use case) and
writes the app into the current directory; pass --skip-install if you want
to install dependencies yourself. With --server local, the managed Zitadel
runtime stores its metadata and data under .zitadel/local/; stop
preserves that data and reset --force deletes it — none of that applies
against a hosted server, which has no local runtime to manage.
Claim your project (Zitadel Cloud only)
If you set up against Zitadel Cloud above, attach the project to your team once the app is up:
npx @zitadel/cli@alpha claim
This opens a browser so you can sign in with your own Zitadel account (not
one of the app's end users) and attach the project to your team. The link
prints before any browser opens, so it works over SSH or headless too
(--no-open); nothing about the running project changes. Claiming only
works within 14 days of running setup — after that, setup a fresh
project instead.
Trying this before deploying to Zitadel Cloud: claiming needs a server with a platform project bootstrapped, which Zitadel Cloud has by default. To exercise the same flow locally today, run the Docker deploy with the platform project enabled and use
http://localhost:8080as the--serverabove — see docker-compose.md and configuration.md § Platform. This box goes away once claiming against Zitadel Cloud is verified end to end.
Manual Docker quick start
Run the API and embedded UIs with Docker Compose when you want to inspect the operator-style stack directly:
cd docs/operations
cp env.example .env
docker compose up -d
| Surface | URL |
|---|---|
| Management console | http://localhost:8080/ui/console/ |
| Sign-in shell | http://localhost:8080/ui/login/ |
| Health | http://localhost:8080/healthz |
Details: docs/quick-start/index.md. To build from source: CONTRIBUTING.md.
Documentation site
The Fumapress/Fumadocs documentation skeleton lives in apps/docs.
moon run docs:dev
moon run docs:build
The docs app bundles the OpenAPI source into a generated reference, exposes
static search, and publishes LLM-friendly text at /llms.txt,
/llms-full.txt, page-level .md URLs, and /mcp.
Current status
This repository is pre-release. The Go server command serves the OpenAPI
surface and embeds the console and login UIs at /ui/console/ and /ui/login/.
CI produces installable snapshots for review, not official releases.
For product direction and the four pillars, see VISION.md.
CI
Pull requests are gated by the GitHub Actions context full-pr, shown in the
pull request UI as ci / full-pr. On a 16-core runner it runs a Go
generated-file drift check, lint, type checks, builds, unit and browser
tests, Go tests including Postgres/Spanner/SQLite dialect integration, a
non-publishing release snapshot, and fresh-app journeys against the snapshot's
npm tarballs.
Changesets version PRs run a smaller release validation path instead, and
Changesets comments give release-intent feedback without adding a blocking
gate. The full step list lives in
.github/workflows/ci.yml and
CONTRIBUTING.md.
Releases
Moon builds the artifacts (Go binaries, containers, archives) and the draft
GitHub Release; Changesets owns versions, npm publishing, and release notes,
with the public packages on one fixed alpha train. Build a local snapshot with
moon run release:snapshot (more in CONTRIBUTING.md). To
cut or recover a release, follow the
release runbook; for when to add a
changeset, see .changeset/README.md; for the
rationale, see ADR 002.
Documentation
¶
There is no documentation for this package.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd/gen_error_schemas
command
gen_error_schemas generates individual OpenAPI error schema files.
|
gen_error_schemas generates individual OpenAPI error schema files. |
|
cmd/gen_event_schemas
command
gen_event_schemas generates per-event-type OpenAPI schemas and the Event oneOf union with discriminator mapping from domain.EventType constants.
|
gen_event_schemas generates per-event-type OpenAPI schemas and the Event oneOf union with discriminator mapping from domain.EventType constants. |
|
cmd/gen_openapi_errors
command
gen_openapi_errors generates OpenAPI default responses for each operation.
|
gen_openapi_errors generates OpenAPI default responses for each operation. |
|
generated
Code generated by ogen, DO NOT EDIT.
|
Code generated by ogen, DO NOT EDIT. |
|
internal/erroranalysis
Package erroranalysis infers, from the Go source itself, which domain error constructors a service interface method can return.
|
Package erroranalysis infers, from the Go source itself, which domain error constructors a service interface method can return. |
|
openapi/endpoints/flow_definitions
Package flow_definitions embeds the default flow definitions for use by the internal package
|
Package flow_definitions embeds the default flow definitions for use by the internal package |
|
openapi/endpoints/schemas
Package schemas embeds the OpenAPI JSON meta-schema files for use by internal packages during schema validation.
|
Package schemas embeds the OpenAPI JSON meta-schema files for use by internal packages during schema validation. |
|
cmd
|
|
|
internal
|
|
|
authz
Package authz holds the shared intermediate representation for permission catalogs.
|
Package authz holds the shared intermediate representation for permission catalogs. |
|
authz/authztest
Package authztest holds shared helpers for authz property and integration tests.
|
Package authztest holds shared helpers for authz property and integration tests. |
|
authz/compiler
Package compiler turns a profile-valid authz model into storage-neutral catalog mutations and query-plan metadata.
|
Package compiler turns a profile-valid authz model into storage-neutral catalog mutations and query-plan metadata. |
|
authz/openfga
Package openfga adapts the upstream OpenFGA language package into Zitadel's authz IR.
|
Package openfga adapts the upstream OpenFGA language package into Zitadel's authz IR. |
|
authz/profile
Package profile enforces the bounded subset of OpenFGA that Zitadel can compile into portable relational query plans (ADR 032 §2).
|
Package profile enforces the bounded subset of OpenFGA that Zitadel can compile into portable relational query plans (ADR 032 §2). |
|
authz/resolver
Package resolver evaluates single-resource permission checks and list authorization against relational authz storage (ADR 032–033 / issue #423).
|
Package resolver evaluates single-resource permission checks and list authorization against relational authz storage (ADR 032–033 / issue #423). |
|
bootstrap/platform
Package platform bootstraps deployment-level platform resources at server startup.
|
Package platform bootstraps deployment-level platform resources at server startup. |
|
crypto/mock
Package cryptomock is a generated GoMock package.
|
Package cryptomock is a generated GoMock package. |
|
domain/mock
Package domainmock is a generated GoMock package.
|
Package domainmock is a generated GoMock package. |
|
errreport
Package errreport centralizes error location and stack capture for structured logging and GCP Error Reporting (ADR 030).
|
Package errreport centralizes error location and stack capture for structured logging and GCP Error Reporting (ADR 030). |
|
httputil
Package httputil provides the hardened egress HTTP client for every fetch of a URL a platform user can inject (schema ingestion today; social login and tenant webhooks later).
|
Package httputil provides the hardened egress HTTP client for every fetch of a URL a platform user can inject (schema ingestion today; social login and tenant webhooks later). |
|
instrumentation/metrics
Package metrics holds the instrument sets the server reports through, one per kind of thing worth measuring, so a component becomes observable by passing an option to its constructor rather than by declaring instruments of its own.
|
Package metrics holds the instrument sets the server reports through, one per kind of thing worth measuring, so a component becomes observable by passing an option to its constructor rather than by declaring instruments of its own. |
|
service/mocks
Package mocks is a generated GoMock package.
|
Package mocks is a generated GoMock package. |
|
staticui
Package staticui serves an embedded SPA under a URL prefix with trailing-slash redirect and index.html fallback for client-side routes.
|
Package staticui serves an embedded SPA under a URL prefix with trailing-slash redirect and index.html fallback for client-side routes. |
|
storage/branding
Package branding holds shared encoding helpers for the branding definition JSON column used by v2 dialect statements.
|
Package branding holds shared encoding helpers for the branding definition JSON column used by v2 dialect statements. |
|
storage/dbtest
Package dbtest provides shared bring-up of databases for v2 storage integration test suites.
|
Package dbtest provides shared bring-up of databases for v2 storage integration test suites. |
|
storage/dialect/authattempt
Package authattempt holds shared helpers for auth-attempt statement dialects.
|
Package authattempt holds shared helpers for auth-attempt statement dialects. |
|
storage/dialect/authz
Package authz holds dialect-independent Wave 1 authz persistence helpers: lifecycle projection (multi-write), membership-edge Filter schema, and catalog row mapping from compiler mutations.
|
Package authz holds dialect-independent Wave 1 authz persistence helpers: lifecycle projection (multi-write), membership-edge Filter schema, and catalog row mapping from compiler mutations. |
|
storage/dialect/compare
Package compare provides shared SQL fragments for dialect statement compilers.
|
Package compare provides shared SQL fragments for dialect statement compilers. |
|
storage/dialect/idgen
Package idgen provides managed resource ID generation for v2 dialects.
|
Package idgen provides managed resource ID generation for v2 dialects. |
|
storage/dialect/idgen/idgenmock
Package idgenmock is a generated GoMock package.
|
Package idgenmock is a generated GoMock package. |
|
storage/dialect/schematest
Package schematest asserts the nullable-binding contract shared by every dialect schema: the Nullable flag is set, the absent state binds untyped nil, and the present state binds the dereferenced value.
|
Package schematest asserts the nullable-binding contract shared by every dialect schema: the Nullable flag is set, the absent state binds untyped nil, and the present state binds the dereferenced value. |
|
storage/dialect/sqlite/migration
Package migration applies SQLite schema migrations using goose.
|
Package migration applies SQLite schema migrations using goose. |
|
storage/flowdefinition
Package flowdefinition holds shared encoding helpers for the flow_definitions definition JSON column used by v2 dialect statements.
|
Package flowdefinition holds shared encoding helpers for the flow_definitions definition JSON column used by v2 dialect statements. |
|
storage/idpconnection
Package idpconnection holds the read plumbing every dialect shares for identity provider connections joined to their revisions.
|
Package idpconnection holds the read plumbing every dialect shares for identity provider connections joined to their revisions. |
|
storage/release
Package release holds shared encoding helpers for the two JSON columns of the releases table — the pinned pointer set and the metadata — used by v2 dialect statements.
|
Package release holds shared encoding helpers for the two JSON columns of the releases table — the pinned pointer set and the metadata — used by v2 dialect statements. |
|
storage/stmttest
Package stmttest holds shared behavioral integration tests for v2 statement implementations.
|
Package stmttest holds shared behavioral integration tests for v2 statement implementations. |
|
storage/userteam
Package userteam binds the user roster read: team memberships joined to the teams they point at.
|
Package userteam binds the user roster read: team memberships joined to the teams they point at. |
|
storage/variable
Package variable holds the dialect-independent row shape, query options and domain mapping for the variables table.
|
Package variable holds the dialect-independent row shape, query options and domain mapping for the variables table. |
|
packages
|
|
|
config/defaults
Package defaults embeds the versioned Zitadel config defaults shared by the CLI and server fallback path.
|
Package defaults embeds the versioned Zitadel config defaults shared by the CLI and server fallback path. |
|
tools
|
|
|
analyzers/cmd/analyzers
command
Command analyzers bundles this repository's custom go/analysis analyzers into one binary.
|
Command analyzers bundles this repository's custom go/analysis analyzers into one binary. |
|
analyzers/egresslint
Package egresslint is a go/analysis analyzer that enforces the single egress-client invariant behind ADR 061: every outbound HTTP or TCP client in production code must come from internal/httputil, the hardened client that applies the SSRF deny list at dial time, caps redirects and body size, and refuses https-to-http downgrades.
|
Package egresslint is a go/analysis analyzer that enforces the single egress-client invariant behind ADR 061: every outbound HTTP or TCP client in production code must come from internal/httputil, the hardened client that applies the SSRF deny list at dial time, caps redirects and body size, and refuses https-to-http downgrades. |