Architecture

Component topology, deployment patterns, data model, and API surface of Zitadel.

Component Topology

flowchart TB
    subgraph Clients["Client Applications"]
        Browser["Browser\n(Login UI)"]
        Console["Console\n(Angular Admin UI)"]
        Apps["Your Applications\n(Web, Mobile, API)"]
    end

    subgraph Zitadel["Zitadel Server (Go Binary)"]
        direction TB
        APIGW["API Gateway\n(connectRPC / gRPC / REST)"]

        subgraph Services["Domain Services"]
            AuthSvc["Authentication\nService"]
            UserSvc["User\nService"]
            OrgSvc["Organization\nService"]
            ProjSvc["Project\nService"]
            SessSvc["Session\nService"]
            ActSvc["Actions\nService"]
        end

        subgraph Core["Core Engine"]
            Cmd["Command Handlers\n(Write Path)"]
            Query["Query Handlers\n(Read Path)"]
            ES["Eventstore\n(Events2 Table)"]
            ProjW["Projection\nWorkers"]
        end

        subgraph Ext["Extensibility"]
            Actions["JS Actions\nRuntime"]
            Hooks["Webhook\nDispatcher"]
            SCIM["SCIM 2.0\nServer"]
        end
    end

    subgraph Data["Data Layer"]
        PG["PostgreSQL\n(Events + Projections)"]
        Redis["Redis\n(Query Cache)"]
    end

    subgraph External["External Systems"]
        IdP["Identity Providers\n(Google, GitHub, Azure AD)"]
        SMTP["SMTP / SMS\n(Notifications)"]
        OTel["OpenTelemetry\nCollector"]
    end

    Browser --> APIGW
    Console --> APIGW
    Apps --> APIGW

    APIGW --> Services
    Services --> Core
    Cmd --> ES
    ProjW --> ES
    Query --> Redis
    ProjW --> PG
    ES --> PG
    Query --> PG

    APIGW --> Ext
    Actions --> Hooks
    SCIM --> UserSvc

    AuthSvc --> IdP
    ActSvc --> SMTP
    APIGW --> OTel

    style Zitadel fill:#1565c0,color:#fff
    style Data fill:#2e7d32,color:#fff
    style External fill:#e65100,color:#fff

Monolithic Binary, Modular Internals

Zitadel ships as a single Go binary with modular internal packages:

Package	Purpose
internal/eventstore/	Event store abstraction, PostgreSQL implementation, push/pop logic
internal/command/	Write-side command handlers, business rule validation
internal/query/	Read-side query handlers, projection consumers
internal/auth/	OIDC, OAuth 2.0, SAML 2.0 protocol implementations
internal/authz/	Authorization resolution, permission checking
internal/api/	gRPC/REST API layer, connectRPC integration
internal/actions/	JavaScript runtime for custom auth flows
internal/crypto/	Encryption, hashing, key management
internal/webauthn/	FIDO2/WebAuthn authentication
internal/notification/	Email, SMS delivery pipeline
internal/idp/	External identity provider integrations
internal/user/	User domain logic (human + machine)
internal/org/	Organization domain logic
internal/project/	Project, application, role management
internal/i18n/	Internationalization
internal/cache/	Redis caching abstraction

API Surface

Zitadel exposes a dual-versioned API surface:

V1 APIs (Legacy, Context-Based)

API	Scope	Base Path	Purpose
Auth API	Per-user	/auth/v1/	User-specific ops (profile, tokens, MFA)
Management API	Per-org	/management/v1/	Org admin ops (users, projects, apps)
Admin API	Instance-wide	/admin/v1/	Instance-level configuration
System API	Self-hosted	/system/v1/	Superordinate control

V2 APIs (Current, Resource-Oriented)

API	Base Path	Purpose
User Service	/v2/users/	User management (preferred for new integrations)
Session Service	/v2/sessions/	Session lifecycle management
Organization Service	/v2/orgs/	Organization management
Project Service	/v2/projects/	Projects, apps, roles
Action Service	/v2/actions/	Actions and webhooks
Feature Service	/v2/features/	Feature flag management
Settings Service	/v2/settings/	Login, password, branding policies
Authorization Service	/v2/authorizations/	User authorization (grants)
OIDC Service	Standard OIDC endpoints	OpenID Connect operations
SAML Service	Standard SAML endpoints	SAML 2.0 operations
SCIM 2.0	/scim/v2/{orgID}/	User provisioning
Web Key Service	/v2/webkeys/	JWT signing key management

API Conventions

Operation	Method	Pattern
Create	POST	/v2/<resource>
Update	POST	/v2/<resource>/<id>
Delete	DELETE	/v2/<resource>/<id>
Set	PUT	/v2/<resource>
Get	GET	/v2/<resource>/<id>
Search	POST	/v2/<resource>/search

All APIs are generated from Protocol Buffer definitions in proto/zitadel/. The server supports connectRPC, standard gRPC, and HTTP/1.1 simultaneously.

Data Model

Hierarchical Resource Model

erDiagram
    INSTANCE ||--o{ ORGANIZATION : contains
    ORGANIZATION ||--o{ USER : manages
    ORGANIZATION ||--o{ PROJECT : owns
    ORGANIZATION ||--o{ IDP_CONFIG : configures
    ORGANIZATION ||--o{ POLICY : enforces
    PROJECT ||--o{ APPLICATION : registers
    PROJECT ||--o{ ROLE : defines
    PROJECT ||--o{ PROJECT_GRANT : shares
    USER ||--o{ USER_GRANT : receives
    USER ||--o{ SESSION : creates
    USER ||--o{ IDP_LINK : links
    PROJECT_GRANT }o--|| ORGANIZATION : "granted to"
    USER_GRANT }o--|| PROJECT : "scoped to"
    USER_GRANT }o--|| USER : "assigned to"
    ROLE }o--|| USER_GRANT : "included in"

    INSTANCE {
        string instance_id PK
        string domain
    }
    ORGANIZATION {
        string org_id PK
        string name
        string state
    }
    USER {
        string user_id PK
        string org_id FK
        string type
        string state
        string email
        string phone
    }
    PROJECT {
        string project_id PK
        string org_id FK
        string name
        string state
    }
    APPLICATION {
        string app_id PK
        string project_id FK
        string name
        string type
    }
    ROLE {
        string role_key PK
        string project_id FK
        string display_name
        string group
    }
    PROJECT_GRANT {
        string grant_id PK
        string project_id FK
        string granted_org_id FK
        string state
    }
    USER_GRANT {
        string grant_id PK
        string user_id FK
        string project_id FK
        string org_id FK
    }

Eventstore Schema

The eventstore uses a custom PostgreSQL schema optimized for append-only operations:

Table	Purpose
eventstore.events2	Immutable event log with composite PK (aggregate_id, sequence)
eventstore.unique_constraints	Enforces uniqueness across events (e.g., unique email per instance)
projections.*	Materialized read-model tables rebuilt from events

Events are inserted atomically via the eventstore.push PostgreSQL function, which handles sequence assignment and unique constraint checking in a single transaction.

Deployment Topologies

Single Instance (Development)

flowchart LR
    subgraph Host["Docker Host"]
        ZA["Zitadel\n:8080"]
        PG["PostgreSQL 17\n:5432"]
    end

    ZA --> PG

Kubernetes Production (HA)

flowchart TB
    subgraph LB["Load Balancer"]
        NGINX["NGINX Ingress\n(TLS Termination)"]
    end

    subgraph K8s["Kubernetes Cluster"]
        subgraph ZA["Zitadel Pods (HPA)"]
            Z1["zitadel-7d4f8"]
            Z2["zitadel-a3b2c"]
            Z3["zitadel-e9f1g"]
        end

        Init["Init Job\n(DB Migrations)"]
        Setup["Setup Job\n(Schema + Defaults)"]

        subgraph Data["Data Plane"]
            PGHA["PostgreSQL HA\n(Patroni / CloudSQL / RDS)"]
            Redis["Redis\n(Cache)"]
        end
    end

    NGINX --> Z1
    NGINX --> Z2
    NGINX --> Z3
    Z1 --> PGHA
    Z2 --> PGHA
    Z3 --> PGHA
    Z1 --> Redis
    Z2 --> Redis
    Z3 --> Redis

    style K8s fill:#1565c0,color:#fff
    style Data fill:#2e7d32,color:#fff

Multi-Cluster / SaaS

flowchart TB
    subgraph Cloud["Zitadel Cloud"]
        ZC["Managed Zitadel\nInstance"]
        PG_C["Managed PostgreSQL"]
    end

    subgraph Remote1["Remote App Cluster 1"]
        App1["Application A"]
    end

    subgraph Remote2["Remote App Cluster 2"]
        App2["Application B"]
    end

    App1 -->|"OIDC / SAML"| ZC
    App2 -->|"OIDC / SAML"| ZC
    ZC --> PG_C

    style Cloud fill:#1565c0,color:#fff

Sources

• Zitadel Architecture Docs
• Zitadel GitHub Repository
• Zitadel API Documentation
• Zitadel Helm Charts

---

How It Works

How Zitadel's event-sourced CQRS engine processes commands, projects read models, handles authentication sessions, and triggers extensibility actions.

Event Sourcing Pipeline

Zitadel's core architecture is built on Command Query Responsibility Segregation (CQRS) with event sourcing. Every state mutation flows through a strict pipeline:

flowchart LR
    subgraph Write["Write Path"]
        API["API Layer\n(gRPC / REST)"]
        Cmd["Command\nValidation"]
        ES["Eventstore\n(PostgreSQL)"]
    end

    subgraph Project["Projection Workers"]
        Sub["Event\nSubscriber"]
        RM["Read Model\nTables"]
    end

    subgraph Read["Read Path"]
        Query["Query\nHandlers"]
        Cache["Redis\nCache"]
    end

    API --> Cmd --> ES
    ES --> Sub --> RM
    Query --> Cache --> RM

Write Path — Command Processing

1. API layer receives a gRPC or REST request, authenticates the caller via Bearer token
2. Authorization check — the proto-annotated permission (e.g., user.write) is validated against the caller's memberships
3. Command handler validates business rules (unique constraints, state preconditions, policy compliance)
4. Event creation — the handler produces one or more domain events (e.g., user.human.added, user.human.password.changed)
5. Atomic persistence — events are appended to the eventstore.events2 table in PostgreSQL using the custom eventstore.push function
6. Unique constraint enforcement — PostgreSQL advisory locks (pg_advisory_xact_lock_shared) prevent concurrent creation of duplicate resources

Event Structure

Every event in the store contains:

Field	Purpose
aggregate_type	Entity category (user, org, project, etc.)
aggregate_id	Unique entity identifier
event_type	Specific mutation (e.g., user.human.added)
sequence	Per-aggregate monotonically increasing counter
position	Global ordering across all aggregates
instance_id	Tenant isolation key
creation_date	Timestamp
payload	Protocol Buffer encoded event data

Read Path — Projection Workers

1. Background projections subscribe to the event stream
2. Each projection builds an optimized read-model table (e.g., projections.users, projections.orgs, projections.project_roles)
3. Projections track their last processed position, enabling idempotent replay
4. Query handlers serve API reads from projection tables
5. Redis cache (optional) reduces database load for hot queries

Authentication Session Lifecycle

OIDC Authorization Code Flow (with PKCE)

sequenceDiagram
    participant User as Browser
    participant App as Application
    participant ZA as Zitadel
    participant ES as Eventstore

    User->>App: Click "Login"
    App->>ZA: GET /oauth/v2/authorize?client_id=...&redirect_uri=...&code_challenge=...
    ZA->>User: Show Login UI (passkey / password / IdP)
    User->>ZA: Authenticate (WebAuthn / password / MFA)
    ZA->>ES: Append session.created, auth.succeeded events
    ZA->>App: 302 Redirect with authorization code
    App->>ZA: POST /oauth/v2/token (code + code_verifier)
    ZA->>ES: Append token.issued event
    ZA->>App: Access token + ID token + refresh token
    App->>ZA: GET /api (Authorization: Bearer <access_token>)
    ZA->>App: JSON response

Session Model (V2 API)

Zitadel's V2 Session API provides fine-grained session management:

1. Session creation — POST /v2/sessions creates a new session with an optional initial check (password, passkey, or IdP)
2. Session updates — PUT /v2/sessions/{id} adds further checks (MFA step, TOTP verification)
3. Session token — returned after successful authentication, used for stateless session tracking
4. Session termination — DELETE /v2/sessions/{id} invalidates the session

Passkey Authentication Flow

sequenceDiagram
    participant Browser as Browser
    participant ZA as Zitadel Server
    participant Auth as Authenticator\n(Platform/Roaming)

    Browser->>ZA: POST /v2/sessions (user identifier)
    ZA->>ZA: Generate WebAuthn challenge
    ZA->>Browser: Return challenge + allowed credentials
    Browser->>Auth: navigator.credentials.get({challenge, ...})
    Auth->>Auth: User verification (biometric / PIN)
    Auth->>Browser: Signed assertion
    Browser->>ZA: POST /v2/sessions/{id} (assertion response)
    ZA->>ZA: Verify signature against stored public key
    ZA->>ZA: Append session.checked.webauthn event
    ZA->>Browser: Session token

Authorization Resolution

When an API request arrives, Zitadel resolves permissions through:

1. Token introspection — extract user ID and scope from the Bearer token
2. Membership lookup — query the user's memberships across organizations, projects, and IAM scopes
3. Role resolution — for each membership, resolve the assigned roles and their associated permissions
4. Context filtering — if the permission requires a context (e.g., project.write:project-123), verify the target resource matches
5. Grant policy check — verify the request passes the organization's policy constraints

flowchart TB
    Req["Incoming API Request"]
    Token["Token Introspection"]
    Member["Membership\nLookup"]
    Roles["Role\nResolution"]
    Perms["Permission\nExpansion"]
    Check["Context\nCheck"]
    Allow{"Allowed?"}

    Req --> Token --> Member --> Roles --> Perms --> Check --> Allow
    Allow -->|Yes| Handler["API Handler"]
    Allow -->|No| Deny["403 Permission Denied"]

Actions & Webhooks Pipeline

Zitadel's extensibility layer intercepts authentication and registration flows:

1. Trigger point — a defined event (e.g., pre creation, post creation, pre userinfo, post authentication) fires
2. Action execution — JavaScript functions (V2 Actions) or HTTP targets are invoked
3. Request modification — actions can modify tokens, add claims, block requests, or redirect users
4. Webhook delivery — events are POSTed to configured HTTP endpoints with full event payload
5. Error handling — failed actions can be configured to block or allow the flow

Action Execution Context

// Example V2 Action: Add custom claims to token
function addAction(token, api) {
    // token contains current JWT claims
    // api provides methods to modify the response
    api.v1.user.setMetadata("custom_role", "premium");
    // Block the request if condition not met
    if (!isAuthorized(token.user)) {
        api.v1.blockRequest("User not authorized");
    }
}

Multi-Tenancy Hierarchy

Zitadel enforces a strict hierarchy for resource isolation:

flowchart TB
    Instance["Instance\n(Self-hosted deployment\nor Zitadel Cloud tenant)"]
    Org1["Organization A\n(Tenant)"]
    Org2["Organization B\n(Tenant)"]
    Proj1A["Project: Billing API"]
    Proj1B["Project: User Portal"]
    Proj2A["Project: Partner Portal"]
    App1["App: Web Client\n(OIDC)"]
    App2["App: Mobile App\n(OIDC)"]
    App3["App: API Service\n(SAML)"]
    Roles1["Roles: admin, editor, viewer"]
    Grant1["Project Grant\n→ Org B"]

    Instance --> Org1
    Instance --> Org2
    Org1 --> Proj1A
    Org1 --> Proj1B
    Org2 --> Proj2A
    Proj1A --> App1
    Proj1A --> App2
    Proj1B --> App3
    Proj1A --> Roles1
    Proj1A -.->|"Delegates\nadmin, editor"| Grant1
    Grant1 -.-> Org2

Project Grants enable cross-organization authorization: Organization A defines roles on a project and grants a subset to Organization B. Organization B can then self-manage user assignments within the delegated roles.

Projection Rebuilding

Because all state is derived from events, read models can be rebuilt from scratch:

1. Truncate the projection table
2. The projection worker replays all events from position 0
3. The read model is reconstructed to match the current event log
4. This enables zero-downtime schema migrations and data repairs

Sources

• Zitadel Architecture Documentation
• Zitadel Eventstore Implementation
• Zitadel Sessions V2 API