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 |
| Open the local console, signed in as the local admin | npx @zitadel/cli@alpha console |
| 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 cannot be changed on this app
afterwards. Use --server local for local development, or point at a hosted
Zitadel Cloud instance if you want the project to belong to your team there.
Local
npx @zitadel/cli@alpha start
npx @zitadel/cli@alpha setup --server local
npm run dev
start boots the local Zitadel runtime and creates a local admin,
admin@zitadel.localhost. It ends by printing a sign-in link for the
management console. That link works once.
setup --server local creates the project and, by default, attaches it to
that admin's team, so the project is owned from the start and zitadel claim
reports it as already owned. If that attempt fails, setup prints a warning and
zitadel claim remains the way to attach it. If you turned the platform
bootstrap off, the server has no local admin and no claiming at all, so the
project simply has no owning team.
Any time you need the console again, print a fresh link:
npx @zitadel/cli@alpha console
The console shows your project and lets you add colleagues as project admins
by their email address. Pass --no-open to print the link instead of opening
a browser. For the admin credential file, how its password is handled, and
how to turn the local admin off, see apps/cli/SKILLS.md.
Open http://localhost:3000/login and register your first user. That user is
an end user of your app, a different identity from the console admin above.
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. The managed Zitadel runtime stores
its metadata and data under .zitadel/local/; stop preserves that data and
reset --force deletes it.
Zitadel Cloud
npx @zitadel/cli@alpha setup --server https://api.zitadel.cloud
npm run dev
A hosted server has no local runtime to manage, so start, stop, reset
and console do not apply there. Once the app is up, attach the project to
your team:
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.
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 |
A fresh Compose server has no project and no user yet, so this console shows
its setup prompt until you seed one (see
docker-compose.md). On the CLI path
above, zitadel console signs you in as the local admin instead.
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). |
|
idp
Package idp is the identity-provider engine: it turns a pinned connection revision into a relying-party client and drives the sign-in ceremony with it.
|
Package idp is the identity-provider engine: it turns a pinned connection revision into a relying-party client and drives the sign-in ceremony with it. |
|
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/deployment
Package deployment holds shared helpers for the deployments table used by v2 dialect statements: list options, the create-time guard, and the encoding of the metadata JSON column.
|
Package deployment holds shared helpers for the deployments table used by v2 dialect statements: list options, the create-time guard, and the encoding of the metadata JSON column. |
|
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/idpidentitylink
Package idpidentitylink holds the read plumbing every dialect shares for identity links.
|
Package idpidentitylink holds the read plumbing every dialect shares for identity links. |
|
storage/project
Package project holds the shared encoding for the projects table's one JSON column -- the password hashing policy -- used by every dialect's statements.
|
Package project holds the shared encoding for the projects table's one JSON column -- the password hashing policy -- used by every dialect's statements. |
|
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. |