Zitrabot

Backend Documentation

Authentication

The backend uses JWT bearer tokens for owner and agent sessions, with API key validation for widget-facing flows. Social login and Google integrations are layered on top of the same account model.

Primary Auth Model

  • Protected user routes expect `Authorization: Bearer <jwt>`.
  • JWTs are signed with `SESSION_SECRET` and expire in 1 day.
  • When no bearer token is present, the generic auth middleware attempts `x-api-key` or `api_key` query auth for supported flows.

Sessions and Passport

  • Express sessions are stored in MongoDB through `connect-mongo`.
  • Passport is mounted globally for Google, GitHub, and Facebook login.
  • OAuth callbacks redirect back to the frontend with a usable token or a query-string error state.

Owner Authentication

These endpoints power signup, verification, login, password recovery, and onboarding. Verification is the first point at which the backend returns a working JWT.

POST/auth/register

Creates a new user, hashes the password, generates a verification code, and sends an account verification email.

Public

Request

  • Send `fullname`, `email`, and `password` as JSON.

Response

  • `201` returns `message` and `userId`.
  • `400` is returned if the email already exists.

Common Errors

  • 400 user already exists
  • 500 registration failed
POST/auth/verify

Validates the verification code and returns the first JWT for the user account.

Public

Request

  • Send `email` and `verificationCode` as JSON.

Response

  • `200` returns `message`, `token`, and `user` with `id`, `fullname`, and `email`.
  • Use the returned token as the bearer token for all dashboard-protected routes.

Common Errors

  • 404 user not found
  • 400 invalid code
  • 400 expired code
  • 500 verification failed
POST/auth/login

Authenticates a verified user and returns a JWT for dashboard access.

Public

Request

  • Send `email` and `password` as JSON.

Response

  • `200` returns `message`, `token`, and `user`.
  • `403` can include `requiresVerification: true` when the credentials are correct but email verification is still pending.

Common Errors

  • 401 invalid credentials
  • 403 verification required
  • 500 login failed
POST/auth/forgot-password

Starts the password reset flow and sends an email if the account exists.

Public

Request

  • Send `email` as JSON.

Response

  • `200` always returns a generic success message so the endpoint does not leak account existence.

Common Errors

  • 500 reset request failure
POST/auth/reset-password

Consumes the reset token and stores a newly hashed password.

Public

Request

  • Send `token` and `newPassword` as JSON.

Response

  • `200` returns `message: Password reset successful`.

Common Errors

  • 400 invalid or expired token
  • 500 reset failure

Authenticated Owner Routes

Once the user has a JWT, the dashboard uses the same token across onboarding, bots, chat handlers, profile management, and billing.

Bearer Header

Authorization: Bearer <jwt>

Onboarding Completion

  • `POST /auth/onboarding/complete` expects a bot-oriented payload including `botName`, `botDescription`, `trainingData`, and optional API integration settings.
  • A successful response returns `message` plus a lightweight `user` object, while the backend creates the initial bot record in the same flow.

Agent and API Key Access

These routes support human handoff and embeddable chat access rather than dashboard ownership flows.

POST/agent/auth/login

Authenticates a support agent and returns a dedicated JWT plus a secure cookie.

Public

Request

  • Send `email` and `password` as JSON.

Response

  • `200` returns `success`, `agent`, and `token`.
  • The `agent` object includes `_id`, `fullname`, `email`, and `status`.

Common Errors

  • 401 invalid credentials
  • 403 inactive account
  • 500 server error
GET/api/keys/validate

Validates a public API key and returns the bot identity needed by the chat widget.

API Key

Request

  • Pass the key via `x-api-key` header or `?key=` query string.
  • If `allowedDomains` is configured, the request `origin` or `referer` must match.

Response

  • `200` returns `valid`, `botId`, `botName`, `theme`, and `position`.
  • `400` is returned when the key exists but is not bound to a specific bot.

Common Errors

  • 401 key required or invalid
  • 403 domain not allowed
  • 500 validation failed