How the Zitadel audit trail supports investigations and audits
When a security or compliance team needs to answer who signed in, who changed an organization, who granted a role, and when, the record to check is Zitadel's event-sourced audit trail. You can reach it through the Console event viewer, the Events API or a SIEM feed, and each route suits a different kind of question. This section explains how the trail supports investigations and audits and what you must confirm before relying on it. The page covers setup, decisions and limits. Exact event coverage and export mechanisms change between releases, so confirm them in the Zitadel documentation for the version you deploy.
Start an investigation in the Console event viewer when the question is scoped to one instance, one organization or one user and an analyst needs to read the sequence quickly. Use the Events API when the same questions recur, when results must be joined with HR or ticketing data, or when a case workflow needs to pull events automatically. Because the trail records changes as a sequence of events, it should let you reconstruct how a role grant or a login policy looked at a past point in time, which is often what an auditor asks. Confirm for your version how each event identifies the actor, the target organization and the timestamp, because those fields decide whether a single entry can answer the question on its own.
For audits, treat the trail as evidence that a control operated, not as the control itself. Decide in advance which samples you will pull, such as administrative role grants, organization changes and sign-ins by privileged users, and test that each sample exports with the actor and timestamp intact. Keep a short written procedure that names who runs each query, where extracts are stored and how they are protected, and who approves them before they go to an auditor. This section does not establish that any independent auditor will accept the trail as evidence. That decision belongs to the auditor and the framework in scope, and your team should raise it with them early.
Plan for three limits before you commit. First, the event store grows with activity and must be backed up and retained under your policy, which the retention planning section covers in detail. Second, a SIEM feed copies events outward, so delivery gaps and parsing failures can hide events from analysts. Run a test action, such as a controlled role change in a non-production organization, and confirm that it appears in the SIEM with the fields your detection rules need. Third, an event that Zitadel does not record cannot be investigated later. Verify coverage for every action you must be able to prove, including identity provider changes and login policy changes, against the documentation for your release before you write it into an audit scope.
Which identity events you need to see and where they should come from
Zitadel exposes its audit data through four surfaces, and each answers a different question. Start with who needs the answer and how quickly they need it, then confirm with Zitadel what each surface exposes in your deployment model and edition before you design retention or forwarding.
Console event viewer for investigations
The Console event viewer lets administrators look up identity events by hand while an investigation is open, such as a disputed sign-in or a suspected account change. It suits one-off reviews by security and support staff. Before you rely on it, confirm with Zitadel which event types the viewer shows, how it filters events by instance, organization and user, and which administrator roles can open it. Test it with a known sign-in before an incident occurs.
Events API for scripted queries
The Events API lets your team pull identity events with scripts for recurring reports, evidence packs for auditors and bulk exports into a data store you control. It supports the decision to build a repeatable extract that does not depend on someone working through the Console. Confirm with Zitadel which event types the API returns, how pagination and filtering work, how far back queries can reach, and which service account or API scope a script needs. Also plan where exports are stored and who can read them.
SIEM streaming for continuous forwarding
SIEM streaming forwards identity events to a security platform as they occur, so detection rules can alert on patterns such as repeated failed sign-ins or changes to administrator access. It supports the decision to respond while activity is still underway. Confirm with Zitadel whether streaming is available in your deployment model and edition, which event types it sends, how delivery is retried after an outage, and who operates the receiving end. Then check that your SIEM can parse the format Zitadel delivers.
Event store retention for history
Event retention decides how long identity history stays available in Zitadel itself, which sets the window for investigations and audit requests that arrive months later. It supports the decision whether to keep history in Zitadel, in a SIEM or in an archive you run. Confirm with Zitadel how long events remain queryable, whether retention can be configured or extended, how deletion works, and what storage effect history has on the PostgreSQL database that backs your deployment. Document the retention period your compliance owners require before go-live.
Console viewer, Events API or SIEM streaming: which fits which team
This table compares the three ways to reach Zitadel audit events: the Console event viewer, the Events API and SIEM forwarding. Read each row by asking which team needs the access, how much operating work it adds and what you must verify in your own Zitadel version before committing. The main takeaway is that the three paths answer different questions, so most organizations need the viewer for investigations and at least one continuous or programmatic path for detection and retention.
| Access path | Team and typical task | Effort to operate | What to confirm |
|---|---|---|---|
| Console event viewer | Investigators and administrators, on demand, looking up what happened for one user or organization | Low. Used through the Console with no separate infrastructure | Who holds access to the viewer, how far back it reads and whether its filters cover your investigation cases |
| Events API | Platform and security engineers, for automation, custom reports and evidence pulls for assessors | Moderate. Needs a service account, scheduled jobs and storage for exported results | The authentication model for API clients, paging and rate limits, and which event types your Zitadel version exposes |
| SIEM forwarding | Security operations, for continuous detection, alerting and retention outside Zitadel | Highest. Needs a forwarding pipeline, a SIEM to run and capacity that grows with event volume | The forwarding method supported in your release, delivery and retry behavior, and who owns retention in the SIEM |
| Event store retention | Platform operations, for keeping events for the period your policy requires | Moderate. Adds database capacity planning and backup scope | The retention window, how purging behaves and whether events can be archived before removal |
Choosing a SIEM receiver for Zitadel events
The SIEM receiver is a separate decision from the Zitadel setting that exports events. The Zitadel setting controls what leaves the identity platform. The receiver controls where those events land, how the security team searches them, which alerts fire and how long they are kept. Make this choice by looking at what the security team already runs and operates well, because a receiver that nobody monitors adds risk rather than visibility. Treat the Zitadel export configuration and the receiver as one integration that must be tested end to end before either is committed.
Wazuh is one open-source option. Its four components are the Wazuh indexer, which stores alerts and provides full-text search and analytics, the Wazuh server, which applies decoders and rules to incoming data, the Wazuh dashboard, and the Wazuh agents installed on endpoints. Wazuh also collects syslog from agentless devices, so a Zitadel host that cannot run an agent may still send events to it. Its dashboard includes prebuilt views for PCI DSS, GDPR, HIPAA and NIST 800-53. Confirm that Wazuh's decoders can parse the exact format Zitadel emits, because a generic syslog feed still needs field mapping before rules and dashboards become useful. Wazuh is distributed under GPL version 2 with an OpenSSL linking exception, which the legal team should review against its own policy.
Graylog is the second example. Its Open edition ingests logs through inputs such as syslog, GELF and Beats, routes messages through streams, and transforms them with processing pipelines before search, dashboards and event definitions for alerting. Graylog Open is free with community support, while the Enterprise and Security editions add features such as a correlation engine and compliance packs under paid licenses. Graylog Open is licensed under SSPL-1.0, which is not an OSI-approved open source license, so legal and procurement teams should decide early whether that license fits their requirements. A Graylog deployment also runs MongoDB for configuration and a Data Node or OpenSearch cluster for storage, which adds components to operate and back up.
Neither Wazuh nor Graylog is an officially supported Zitadel receiver unless Zitadel or the vendor confirms that in writing. Before committing, ask Zitadel which export format and transport it documents for audit events and confirm the current version supports it. Then ask the chosen SIEM vendor whether it accepts that format and transport without custom code. Run a test with sample events from a non-production instance and check field mapping, timestamps, search results, one alert and the retention behavior of the receiver. Record the results and the open questions in the design record, so the decision can be revisited when either product changes.
How to set up audit access and SIEM forwarding
This sequence takes Zitadel audit events from a confirmed baseline to a production SIEM feed that analysts can search and trust. Each step ends with a check, so the team knows which events it can find, who can read them and how their timestamps line up before any retention period is set. The output is a documented, tested path from the Console event viewer and Events API to the SIEM.
Confirm the Zitadel version and deployment model
An engineer on the platform team records the exact Zitadel version, the deployment method (binary, Docker Compose or Kubernetes with the official Helm chart) and the PostgreSQL version, which must fall in the supported range of 14 through 18. Before planning any queries or forwarding, check the release notes for your version to confirm which audit features it exposes. Done when the team has a written record of the version, deployment model and database version, and the security owner has approved that record as the baseline for the remaining steps.
Decide which instances and organizations the events cover
The security owner and the platform lead list every Zitadel instance in scope, then the organizations inside each instance that hold workforce or customer identities. Instances are isolated tenants with full data isolation, so the forwarding design needs one clearly named source per instance or a documented way to tag events by instance. Record which organizations feed which investigation or audit request. Done when the scope list names each instance and organization, its owner, and the SIEM index or tenant that will receive its events, and the reviewers have accepted it in writing.
Grant administrators least-privilege access to the event viewer and API
The Zitadel administrator for each instance creates separate access for people who read audit events and for the service account that calls the Events API, limited to the instances and organizations from the previous step. Read access to events should stay separate from rights to change users, applications or policies. Confirm the role names, grant options and the way the event viewer and Events API authorize requests in the Zitadel documentation for your version before assigning anything. Done when a reviewer can open the event viewer for the scoped organization, the service account reads the same events, and a negative test shows that neither account can change users or policies.
Test a query or export with a known test event
A platform engineer makes a harmless, labeled change in a non-production instance, such as creating a test user or changing a test application setting. The engineer records the time of the change, the actor and the target identifiers. The team then finds that event in the Console event viewer and retrieves it through the Events API, comparing the event type, actor, target and timestamp with the record. Done when the event appears in both paths with the expected details, and a second team member can reproduce the lookup from the written record without help from the person who made the change.
Configure forwarding to a non-production SIEM receiver
The platform team builds the forwarding path from Zitadel to a SIEM receiver in a non-production environment, using the streaming method documented for the Zitadel version in use. The receiver may be Graylog, Wazuh or another SIEM your team already runs, so confirm which input formats it accepts and what licensing applies before building. Keep the receiver's storage and access controls separate from production. Done when the test events from the previous step arrive in the non-production receiver with the same identifiers, and the forwarding job reports no errors across the test window the team set.
Validate parsing and timestamps in the SIEM
A SIEM analyst checks that each forwarded event is parsed into separate fields for event type, actor, target, organization and instance, and that no essential field is truncated or merged. Compare the timestamp shown in the SIEM with the time recorded for the test change, and confirm that the time zone is handled consistently between Zitadel, the receiver and the host clocks. Restart the receiver once to confirm the parsing rules persist. Done when a written parsing test passes for at least one event of each type the team expects to investigate, and the analyst signs off on the field mapping.
Move forwarding to production with a documented retention period
After the earlier steps pass, the security owner sets the retention period for audit events and records who may change it and how legal holds and audit requests are handled. The event store and the SIEM may use separate retention settings, so confirm and document each one. Agree the required period with your compliance lead and auditors, since it depends on your obligations and their expectations. Enable production forwarding with a written rollback plan, then check that the first production events arrive as expected. Done when the retention record is approved, production events arrive, and the runbook names an owner for each setting.
How long to keep the Zitadel event store and how to size it
Retention for the Zitadel event store is a database sizing and backup decision as much as a compliance one. Self-hosted Zitadel keeps its data in PostgreSQL, with versions 14 through 18 supported, so every event the audit trail depends on lives in a database that your platform or database team must provision, monitor and back up. The retention period you choose drives table growth, backup size, restore time and disk capacity. Set it with the database owners before go-live, not after the first storage alert. Confirm in the Zitadel documentation for your exact release whether events are pruned automatically, whether pruning is configurable, and how the Console event viewer and Events API behave when older records age out.
The core trade-off is whether history stays in Zitadel or moves to a SIEM or archive. Keeping events in Zitadel lets investigators query them through the Console and the Events API without a second system, but the storage grows inside the same database that serves logins. Exporting events to a SIEM such as Wazuh or Graylog, or to an archive, moves long-term retention to a system sized for log volume, which lets the Zitadel database hold a shorter window. The cost is another pipeline to operate, its own retention policy and proof that the exported copy is complete and tamper-evident. Decide by listing the questions your investigations and auditors need answered, and the age of records each question requires.
Graylog's architecture guidance offers one sizing pattern you can use as an analogy. It advises sizing log storage as daily ingest multiplied by retention days, times 120 percent, and giving the message journal 3 to 5 times daily ingest on SSDs. This formula comes from Graylog's storage model, not Zitadel's, so it does not tell you how large Zitadel's event records will be or how many a login-heavy tenant will produce. Illustrative arithmetic: if a deployment produced 1 GB of events per day and kept 90 days, the pattern gives 1 × 90 × 1.2 = 108 GB of storage before database overhead, indexes and backups are added. Use the structure of the calculation, then replace each input with your own measurements.
Measure event volume before you commit to a number. Run a representative test instance under realistic login, provisioning and administrative activity, and record how fast the event tables grow per day, including peak periods such as the start of a working week. Track the full database size, not only the event tables, and measure how long a restore from a backup takes at that size. Then ask Zitadel and your PostgreSQL provider to confirm the event pruning behavior and how it interacts with backup retention, so that deleting old events in the live database does not also remove the only copy you are required to keep.
Turn the findings into decisions and a quote. Define the retention period for each event category, the export destination and its verification method, and who approves any exception for legal hold. Ask any implementation partner to price the measurement work, retention configuration, export pipeline and restore testing as separate line items, and ask which parts recur, such as monitoring, backup storage and periodic restore tests. Your own infrastructure costs for storage, backup and the SIEM license or hosting continue after the project ends, so include them in the sizing decision from the start.
Protecting audit data and controlling who can read it
Audit events are only useful if the people reading them cannot quietly change them and the channel carrying them is protected. The cards below cover who may read events across organizations, how the SIEM export is secured, how exported logs can be checked for tampering, how the PostgreSQL database holding events is backed up, and how review duties stay separate from identity administration.
Limiting who can read events
Zitadel separates tenants into instances and organizations, so the first decision is which administrators may read events for which organizations. Confirm whether Console event viewer access and Events API tokens can be scoped to a single organization. Then test that an administrator in one organization cannot retrieve events belonging to another. Record which roles hold this permission and review them on a fixed schedule.
Protecting the export channel
Streaming events to a SIEM moves identity data across a network boundary, so both the transport and the receiving account need controls. Confirm which transport encryption options the streaming feature supports and how the SIEM authenticates the sender. Check whether credentials can be rotated without an outage, and whether network policy blocks any unencrypted path to the receiver. Document the endpoint addresses and certificate authority in your runbook.
Integrity of exported logs
A SIEM copy supports an investigation only if its contents can be shown to be unchanged. Ask Zitadel whether exported events carry signatures or hashes that a reviewer can verify. If they do not, choose a compensating control, such as write-once storage, hash chaining in the receiving pipeline or restricted delete rights on the log store. Test by altering a copied record and confirming the change is detected. Auditors and certification bodies decide whether the result is sufficient.
Backing up the event store
Events are held in the PostgreSQL database that Zitadel uses, so backups must cover it with the identity data it describes. Confirm that your PostgreSQL version falls within the 14 through 18 range Zitadel supports. Verify that backups include the event data and that point-in-time recovery has been tested. Document how a restore is checked against a known sequence of events.
Separating administration from review
The people who change identity settings should not be the only people who can see the record of those changes. Assign event review to a group with read-only access and no rights to modify users, roles, policies or streaming configuration. Confirm that only the platform team can change the streaming setup. Log the review group's own access so that reviewers can be reviewed.
What does an audit trail and SIEM setup cost and take?
What drives the cost of a Zitadel audit trail and SIEM setup?
Scope is the main driver. The cost depends on how many Zitadel instances and organizations are covered, whether you stream events to a SIEM or only review them in the Console, which receiver you use, how long events are kept, and how much testing the integration needs.
The receiver changes the cost most. Graylog's pricing page lists Graylog Open as free with no volume limits and community support, while Graylog Enterprise starts at 15,000 US dollars per year. Wazuh is distributed under the GNU General Public License version 2. Licence fees are only one line, though. Storage recurs, and Graylog's system architecture guidance advises sizing log storage as daily ingest times retention days times 120 percent. Design, connector build and testing are one-time costs, while storage, receiver licensing and operations recur. Ask for each of these as a separate line in the quote.
Can our team set up Zitadel audit trail and SIEM streaming alone?
Yes, for simple use. Reviewing events in the Console event viewer during an investigation needs no integration work, and a small team can manage it with Zitadel's documentation.
Streaming identity events to a SIEM, building the receiver and setting retention take more experience. Your team has to understand the event payloads, handle delivery failures and configure how old data is removed so storage does not grow without limit. Graylog's index model documentation describes retention that deletes the oldest indices, which is one setting to confirm before go-live. A team that already runs a SIEM and has an engineer comfortable with event pipelines can often take this on. A team without that experience usually benefits from a partner for design and testing. Confirm the current streaming options in Zitadel's documentation before you decide.
How long does a Zitadel audit trail and SIEM setup take?
It depends on the confirmed scope and on whether you already have a SIEM. No fixed duration is available for this work, so ask for a timeline in the written scope and check it against the phases listed there.
The timeline usually moves with a few factors: the number of Zitadel instances and organizations to cover, whether a receiver must be installed or an existing one extended, the number of event types you need to route and parse, how long it takes to agree a retention policy, and the number of test cycles needed to show that events arrive complete. DeployOpen agrees fixed scopes, deliverables and timelines in writing before work starts, so the duration belongs in that document and should be tied to milestones and acceptance tests.
What does a Zitadel SIEM setup need from our team?
The work needs named people and access before it starts. Plan to provide access to your SIEM or log platform, including an account that can create inputs, streams or indices. You will also need a test environment where Zitadel and the receiver can be exercised without touching production identity data.
Name an owner for identity, for security operations and for the SIEM. Provide a written retention policy that states how long audit events must be kept and where they must live. Also provide the hosts or cloud accounts where the receiver runs, the network paths from Zitadel to the receiver, and a change window for the production switch. The retention policy is the item most often missing, and it sets the storage size, so settle it early.
Does Zitadel Enterprise support change the effort for a SIEM setup?
It can, but confirm what the support covers first. Zitadel's pricing page states that the Enterprise plan offers custom support agreements and technical account management. It does not list the specifics, so ask Zitadel in writing whether support includes help with streaming configuration, troubleshooting event delivery, upgrades that affect the event store, or escalation during an incident.
Vendor support covers the product side. It does not replace your own decisions on receiver design, retention and testing. Enterprise pricing is custom, so request it in writing and compare it with the scope of the setup work. DeployOpen plans, implements, hardens, backs up, upgrades and documents self-hosted platforms in your infrastructure, so ask us how a Zitadel support agreement would sit alongside that work.
What should a written quote for audit trail and SIEM work include?
It should start with the scope. List the Zitadel instances and organizations covered, the event types, whether streaming and Console review are both included, and the receiver and its version.
Next, separate one-time work, such as design, connector build, parsing, dashboards, testing, documentation and handover, from recurring items, such as storage, receiver licences or subscriptions, support and any retainer. State the assumptions the price relies on, including your SIEM access, test environment and retention policy, and what happens if any of them arrive late. Ask for milestones, the acceptance tests that prove events arrive complete, and the named owner for each deliverable. DeployOpen provides fixed-scope quotes agreed in writing before work starts and does not publish a price list.
Limits to confirm before you commit to a design
Several limits on Zitadel's audit trail come from the product version, deployment model, edition and license, not from your design. Each card names one item to confirm with Zitadel or counsel, and each answer changes the SIEM pipeline, retention plan or code boundary you build. Close them in writing before you commit.
Event types in your version
The Console event viewer and the Events API expose a defined set of event types, and that set can change between releases. Ask which event types your version emits and whether each one records the actor, target and organization your investigations need. Check the v4.19.5 release notes, released 15 October 2026, or the notes for the version you run, and write the answer into your event catalog before you map detections to it.
SIEM streaming availability
Streaming identity events to a SIEM may be offered for some deployment models and editions and not others. Confirm whether SIEM streaming is available for your deployment model, whether it covers self-hosted instances, and which Zitadel edition includes it. Get the answer in writing from Zitadel, because your choice of SIEM and the collector you build both depend on it. Do not start the pipeline design until this question is closed.
Event retention and pruning
Because Zitadel uses PostgreSQL as its database, event retention feeds directly into database sizing, backup scope and restore time. Ask how long events are kept, whether pruning runs automatically, and whether pruned events remain reachable through the Console or the Events API. Schedule an export to long-term storage that finishes before any pruning window opens, and test a restore that includes the audit data.
Events API rate and volume limits
A SIEM poll or bulk export is only as fast as the API allows, and a large backfill can compete with live authentication traffic on the same cluster. Ask Zitadel for documented rate limits, page size limits and any throttling behavior. Test a backfill against a staging instance running your version, and design the collector to handle throttled responses with backoff and a stored cursor so it resumes without gaps.
AGPL 3.0 for modified core
Zitadel moved its core, Console and hosted login from Apache 2.0 to AGPL 3.0 with v3.0 on 31 March 2025. If you modify the core and run it for users over a network, AGPL source-offer obligations may apply to those modifications. Record every change to core components, and take the question to legal counsel before you build custom event handling into the core.
Apache 2.0 for client code
APIs, SDKs, proto definitions and Helm charts remain Apache 2.0, so a collector or connector that only calls the Events API as a client is generally governed by that license. Keep such code outside modified core components, and document the boundary in your design. Have legal counsel review the licensing position for each component, because the answer depends on what you modify and how you deploy.
How DeployOpen scopes and delivers the audit trail and SIEM work
DeployOpen plans, builds and documents Zitadel audit trail and SIEM streaming inside your own infrastructure, starting from the questions your investigators and auditors need to answer. Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts. Your team keeps the configuration, runbooks and retention settings after handover.
How we scope
- The written scope names which Zitadel instances, organizations and event types are in the audit trail.
- Retention targets for the event store are set with your legal, compliance and security owners before build.
- Scope also covers which downstream SIEM receives identity events and who owns each alert path.
How we build
- Test which Console event viewer filters and Events API queries your investigators need, against a non-production instance.
- Build the streaming path to the SIEM with delivery checks, including what happens when the receiver is down.
- Where the SIEM is Wazuh or Graylog, set up receiving, parsing and retention on those platforms in your infrastructure.
How we hand over
- Documented runbooks cover how to search events, export records and respond to a streaming failure.
- Retention and pruning steps are written down so your operators can run them without outside help.
- Handover includes the configuration files and a checklist your team repeats after each Zitadel upgrade.
How we support
- Ongoing support is available as a retainer for upgrades, log source changes and SIEM rule tuning.
- Continuous security testing can check that event access and export paths stay restricted over time.
- DeployOpen prepares evidence for compliance assessments, but independent auditors issue any audit reports.
