Cron Setup

CareNova includes a background cleanup job that runs daily to maintain authentication security and remove stale data. This job must be scheduled externally — it does not run automatically.

What the Cron Job Does

The cleanup endpoint runs two operations every time it is called:

1. Authentication log cleanup Deletes entries from login_attempts and auth_audit_log that are older than 24 hours. This keeps the auth tables lean and ensures the rate limiting system only counts recent attempts.

2. Session cleanup Removes expired and revoked entries from the user_sessions table. This prevents the session table from growing indefinitely over time.

Neither operation affects patient data, appointments, invoices, or any clinical records. It only touches authentication and session tables.

The Cron Endpoint

GET /api/cron/cleanup-auth

Full URL example:

https://yourdomain.com/api/cron/cleanup-auth

Authentication — Authorization Header

The endpoint is protected by CRON_SECRET. Every request must include this value in the Authorization header using Bearer format:

Authorization: Bearer YOUR_CRON_SECRET

⚠️ The endpoint uses the Authorization: Bearer header — not a query parameter. Requests without the correct header return a 401 Unauthorized response and no cleanup is performed.

Generating a Secure CRON_SECRET

Generate a strong random value for your secret:

openssl rand -base64 32

Add it to your .env.local:

CRON_SECRET=your-generated-secret-here

And add the same value to your Vercel environment variables under Settings → Environment Variables.

Recommended Schedule

Run the cleanup job once daily. Running it more frequently provides no benefit since the cleanup only targets records older than 24 hours.

Setup Option A — Vercel Cron Jobs (Recommended)

If you are hosting on Vercel, use the built-in cron jobs feature. This is the simplest option and requires no external service.

Create a vercel.json file in the root of your project if one does not already exist:

{
  "crons": [
    {
      "path": "/api/cron/cleanup-auth",
      "schedule": "0 2 * * *"
    }
  ]
}

Vercel will automatically call the endpoint daily at 2:00 AM UTC.

Passing the Secret on Vercel

Vercel cron jobs call your endpoint internally and include a special header automatically. However, CareNova validates CRON_SECRET directly, so you need to handle this in the route.

The route at app/api/cron/cleanup-auth/route.ts reads the Authorization header and compares it to process.env.CRON_SECRET. As long as CRON_SECRET is set in your Vercel environment variables, the job will authenticate correctly.

Vercel cron jobs are available on all plans including the free Hobby plan — up to 2 cron jobs per project.

Helpful resources:

• Vercel Cron Jobs documentation

Setup Option B — External Cron Service

If you are not on Vercel, use any HTTP-capable cron service to call the endpoint on a schedule.

Recommended services:

Configuration for External Services

When configuring the cron job in your chosen service:

Make sure the service supports custom request headers — this is required to pass the Authorization: Bearer value.

Setup Option C — GitHub Actions

If your project is on GitHub, you can use GitHub Actions as a free cron scheduler.

Create .github/workflows/cron-cleanup.yml:

name: CareNova Auth Cleanup

on:
  schedule:
    - cron: '0 2 * * *'   # Daily at 2:00 AM UTC
  workflow_dispatch:        # Allow manual trigger

jobs:
  cleanup:
    runs-on: ubuntu-latest
    steps:
      - name: Run auth cleanup
        run: |
          curl -X GET \
            -H "Authorization: Bearer ${{ secrets.CRON_SECRET }}" \
            https://yourdomain.com/api/cron/cleanup-auth

Add CRON_SECRET to your GitHub repository secrets: Settings → Secrets and variables → Actions → New repository secret

GitHub Actions cron jobs may be delayed by up to 15 minutes on free plans during periods of high demand. This is acceptable for a daily cleanup job.

Testing the Cron Job

Before relying on your scheduled job, test the endpoint manually to confirm it is working correctly.

Using curl:

curl -X GET \
  -H "Authorization: Bearer YOUR_CRON_SECRET" \
  https://yourdomain.com/api/cron/cleanup-auth

A successful response returns:

{
  "success": true,
  "message": "Cleanup completed"
}

An unauthorized response (wrong or missing secret):

{
  "error": "Unauthorized"
}

Replace YOUR_CRON_SECRET with the actual value from your .env.local or Vercel environment variables — not the literal string.

Security Best Practices

• Use a strong secret — generate with openssl rand -base64 32

• Never expose CRON_SECRET publicly — do not commit it to your repository or include it in client-side code

• Use HTTPS only — never call the endpoint over HTTP in production

• Monitor for 401 responses — if your cron service reports failures, check that the secret in your environment variables matches the one configured in your cron service

Troubleshooting

Endpoint returns 401 Unauthorized:

• Confirm CRON_SECRET is set in your environment variables (Vercel or .env.local)

• Confirm the header is exactly Authorization: Bearer YOUR_SECRET — no extra spaces, correct capitalization

• Confirm you are not using a query parameter (?secret=) — this format is not supported

Endpoint returns 500:

• Confirm DATABASE_URL is correctly set and the database is reachable

• Check Vercel function logs for the specific error message

Vercel cron job not triggering:

• Confirm vercel.json is in the project root and committed to your repository

• Confirm the project has been redeployed after adding vercel.json

• Check Vercel Dashboard → Settings → Cron Jobs to confirm the job is listed and active

• Vercel cron jobs require the Hobby plan or higher — confirm your plan supports them

Next Step

The Configuration collection is now complete. Continue to the Modules collection to learn how each dashboard module works in detail, or return to the First-Time Setup Checklist to verify your deployment is fully configured.