Background workers start inside the AuthOS API process. The qualified topology is a single worker per database; do not assume that every job is safe to run from multiple independent worker deployments.
Durable queue processor
The system_jobs queue currently handles email and webhook-delivery jobs.
Workers claim jobs atomically, enforce configured concurrency, mark successful
jobs complete, and record failures for retry or permanent failure. A queued
webhook is re-authorized against the current tenant and webhook state before
delivery, so disabling either prevents stale delivery.
Maintenance workers
The API process also starts workers for:
- provider-token refresh;
- expired device-code cleanup;
- expired OAuth and SAML state cleanup;
- delayed cleanup of soft-deleted users;
- durable audit-outbox reconciliation; and
- periodic Prometheus queue metrics.
Intervals derive from runtime configuration. Treat source defaults as defaults, not service-level guarantees.
Operational checks
- Use
/health/readyfor readiness, not proof that every downstream delivery has completed. - Monitor queue depth, failed jobs, webhook delivery records, and worker errors.
- Keep encryption available: secret-bearing jobs and token refresh must not fall back to plaintext.
- Quiesce API and worker traffic before running the documented secret-rewrap maintenance procedure.
- Back up the database before destructive maintenance.
There is no public API for arbitrary custom jobs. Unknown queued job types are not an extension mechanism and must not be used for application work.