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¶
- GDPR & privacy: exporting and erasing one user's data
- Backup & disaster recovery: deleted rows stay in older backups until those expire