Skip to main content

Email-based password reset

Starting from v1.9.0, local users can request password reset links by email.

Overview​

Password reset flow:

  1. User calls POST /api/auth/forgot-password with their email.
  2. System sends a reset link if a matching local account exists.
  3. User submits POST /api/auth/reset-password with the token and a new password.

Security behavior:

  • POST /api/auth/forgot-password always returns 200 to avoid email enumeration.
  • Reset tokens are single-use and hashed at rest.

Configure Email Delivery​

Development mode (default):

EMAIL_PROVIDER=console

In console mode, reset links are written to backend logs/stdout.

SMTP mode:

EMAIL_PROVIDER=smtp
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USERNAME=docbot
SMTP_FROM=DocBot <noreply@example.com>
SMTP_STARTTLS=true
# Or implicit TLS mode when required:
# SMTP_TLS=true

Provide SMTP credentials securely:

echo "<smtp-password>" | docker secret create smtp_password -

Set SMTP_PASSWORD to use that Docker secret in your deployment.

Seed the Default Admin Email​

Set DEFAULT_ADMIN_EMAIL so the first-boot seeded admin account can use password reset immediately:

DEFAULT_ADMIN_EMAIL=admin@example.com

You can also let users self-service their address later via:

  • PUT /api/auth/me/email

Optionally enforce email presence for user management with:

AUTH_REQUIRE_EMAIL=true

Rate Limiting​

The reset endpoints are protected by dedicated nginx limits:

RATE_LIMIT_RESET=10r/m
RATE_LIMIT_RESET_BURST=20

These apply to:

  • POST /api/auth/forgot-password
  • POST /api/auth/reset-password

OIDC Users​

Password reset applies to local users.

OIDC-only users have NULL local passwords and must reset credentials at their identity provider (IdP), not in RAG-DocBot.

See also: Environment Variables and SSO / OIDC.