Cron jobs

Scheduled maintenance and cleanup tasks

Overview

Cron job endpoints are scheduled tasks that run automatically at specified intervals. These endpoints handle maintenance operations like cleaning up expired sessions, rate limits, and creating backups.

All cron endpoints are secured with the CRON_SECRET environment variable and are automatically invoked by Vercel’s cron scheduler.

Authentication

All cron endpoints require Bearer token authentication:

Authorization · string · required

Bearer token containing the CRON_SECRET value.

Format: Bearer YOUR_CRON_SECRET

Vercel automatically sends this header when invoking scheduled cron jobs.

Requests without a valid CRON_SECRET will receive a 401 Unauthorized response.

Endpoints

Cleanup admin sessions

Deletes expired admin session records that are older than 7 days.

Path: /api/cron/cleanup-admin-sessions

Method: GET

Schedule: Daily at 4:00 AM UTC (0 4 * * *)

cURL

curl https://your-domain.com/api/cron/cleanup-admin-sessions \
  -H "Authorization: Bearer YOUR_CRON_SECRET"

ok · boolean · required

Indicates whether the cleanup was successful.

deleted · number · required

Number of expired admin sessions deleted.

See implementation: app/api/cron/cleanup-admin-sessions/route.ts:9

---

Cleanup rate limits

Deletes stale authentication verification rate limit counters.

Path: /api/cron/cleanup-rate-limits

Method: GET

Schedule: Daily at 4:10 AM UTC (10 4 * * *)

cURL

curl https://your-domain.com/api/cron/cleanup-rate-limits \
  -H "Authorization: Bearer YOUR_CRON_SECRET"

ok · boolean · required

Indicates whether the cleanup was successful.

deleted · number · required

Number of rate limit records deleted.

See implementation: app/api/cron/cleanup-rate-limits/route.ts:9

---

Backup event store

Creates periodic backups of the event store CSV payload.

Path: /api/cron/backup-event-store

Method: GET

Schedule: Daily at 4:20 AM UTC (20 4 * * *)

cURL

curl https://your-domain.com/api/cron/backup-event-store \
  -H "Authorization: Bearer YOUR_CRON_SECRET"

ok · boolean · required

Indicates whether the backup operation completed successfully.

message · string · required

Human-readable description of the result.

backup · object

Backup metadata (only present when backup was created).

prunedCount · number

Number of old backups that were deleted to maintain retention limits.

skipped · boolean

Indicates the backup was skipped (e.g., no data available).

See implementation: app/api/cron/backup-event-store/route.ts:9

Error responses

All cron endpoints use a consistent error response format:

401 Unauthorized

{
  "error": "Unauthorized"
}

error · string · required

Error message describing what went wrong.

ok · boolean

Always false for 500 errors.

Status codes

Code	Description
200	Operation completed successfully
401	Missing or invalid CRON_SECRET
500	Internal server error during execution

Cron schedule configuration

Cron jobs are configured in vercel.json:

vercel.json

{
  "crons": [
    {
      "path": "/api/cron/cleanup-admin-sessions",
      "schedule": "0 4 * * *"
    },
    {
      "path": "/api/cron/cleanup-rate-limits",
      "schedule": "10 4 * * *"
    },
    {
      "path": "/api/cron/backup-event-store",
      "schedule": "20 4 * * *"
    }
  ]
}

Schedule format uses standard cron syntax: minute hour day month weekday

All times are in UTC.

Environment variables

CRON_SECRET · string · required

Secret token used to authenticate cron job requests.

Set this in your Vercel project environment variables. Vercel automatically includes it in the Authorization header when invoking scheduled crons.

Implementation details

All cron endpoints follow a consistent pattern:

1. Extract Bearer token from Authorization header
2. Validate token against CRON_SECRET environment variable
3. Execute the scheduled task (cleanup, backup, etc.)
4. Return operation results with appropriate status codes
5. Set no-cache headers to prevent response caching

Manual invocation

While cron jobs run automatically on schedule, you can manually trigger them for testing:

curl https://your-domain.com/api/cron/cleanup-admin-sessions \
  -H "Authorization: Bearer YOUR_CRON_SECRET"

Only invoke cron endpoints manually for testing or emergency maintenance. Normal operations should rely on the automatic schedule.