Skip to content

Data retention

A scheduled cleanup deletes rows that have expired, so the database does not keep sign-in data longer than it needs to. It is on by default. It runs every 15 minutes in batches of 500 rows with FOR UPDATE SKIP LOCKED, so it is safe with several replicas.

What is deleted

Data Deleted
OAuth2 authorizations one hour after their last token expired (the refresh token included); abandoned ones (no token yet, e.g. a consent or PAR request never finished) after a day
Browser sessions kept in PostgreSQL after they expire (5-minute grace)
One-time codes when older than two days
Magic-link, e-mail-verification and e-mail-change tokens a day after they expired
Audit events not stored by HelixIAM (see below)

Flow state, rate limits and wallet transactions have their own sweepers (see High availability).

Audit events are kept by your audit tool

HelixIAM keeps no audit events in its database, so it has no audit retention setting. Each event is a JSON line on stdout; how long it is kept depends on your logging, archiving and supervisory obligations and is set in your audit tool (see Events & audit and Observability). Decide that first. The audit_log table and its retention setting were removed; see Upgrading for the export to make before upgrading an older installation.

Settings

Property Environment variable Default
helix.retention.enabled HELIX_RETENTION_ENABLED true
helix.retention.interval HELIX_RETENTION_INTERVAL 15m
helix.retention.batch-size HELIX_RETENTION_BATCH_SIZE 500
helix.retention.max-batches-per-run HELIX_RETENTION_MAX_BATCHES_PER_RUN 200
helix.retention.authorization-grace HELIX_RETENTION_AUTHORIZATION_GRACE 1h
helix.retention.authorization-unfinished HELIX_RETENTION_AUTHORIZATION_UNFINISHED 1d
helix.retention.session-grace HELIX_RETENTION_SESSION_GRACE 5m
helix.retention.code-max-age HELIX_RETENTION_CODE_MAX_AGE 2d
helix.retention.token-grace HELIX_RETENTION_TOKEN_GRACE 1d

Durations use Spring's format (30m, 12h, 400d). In the Helm chart: retention.enabled and retention.interval.

helm upgrade --install helixiam oci://ghcr.io/melmarzgioui/helixiam/charts/helixiam --version 1.1.0-rc.33 ... --set retention.interval=15m

Metrics

helix_retention_deleted_rows_total{table} counts deleted rows per table and helix_retention_run_seconds times each run; both are on /actuator/prometheus (see Observability & health).

See also