Skip to main content

RESTful API Architecture & Authentication Overview

HiTech Insurance exposes a robust, security-hardened suite of 39 RESTful API endpoints serving web lead ingestion, partner programmatic syndication, marketing webhooks, form submissions, customer self-service, media delivery, and real-time operational telemetry.

1. Unified Base URLs & Environment Routing​

EnvironmentBase URLOpenAPI Specification URLSwagger UI Explorer
Productionhttps://hitechinsurance.aihttps://hitechinsurance.ai/api/docs/openapi.jsonhttps://hitechinsurance.ai/api/docs
Staginghttps://hitech-webapp-staging.azurewebsites.net/api/docs/openapi.json/api/docs
Local Developmenthttp://localhost:3000http://localhost:3000/api/docs/openapi.jsonhttp://localhost:3000/api/docs

2. Authentication & Authorization Schemes​

The API enforces five distinct security authentication mechanisms depending on the route's threat surface:

Scheme 1: Partner Ingestion HMAC-SHA256 (/api/leads/*)​

Used for programmatic, server-to-server lead ingestion by approved syndication partners (e.g. Falcon, auto dealer DMS systems):

  • Headers:
    • x-partner-id: Unique registered partner alphanumeric ID.
    • x-timestamp: ISO 8601 UTC timestamp. Replayed requests outside a 5-minute skew window are rejected.
    • x-signature: Hex-encoded HMAC-SHA256(canonicalPayload, partnerSecret).
  • Verification: Validated using crypto.timingSafeEqual to thwart timing attacks.

Scheme 2: Dual-Tier reCAPTCHA Bot Defense (/api/forms/*)​

Used on public client-facing forms to prevent spam submissions and distributed bot fills:

  • Header / Body: g-recaptcha-response (or recaptchaToken).
  • Assessment: Google reCAPTCHA v3 score evaluation (threshold: 0.5) with fallback to v2 interactive checkbox challenge.
  • Fail-Open Quarantine: Leads failing verification are saved to QuarantinedLead rather than dropped, ensuring zero loss of legitimate customer business.

Scheme 3: Social & Ad Network Webhooks (/api/webhooks/*)​

  • Meta Ads: Evaluates the X-Hub-Signature-256 HMAC header against META_APP_SECRET. Handles Meta verification challenge (hub.challenge).
  • Google Ads: Authenticates bearer token in Authorization: Bearer <token> against GOOGLE_ADS_WEBHOOK_KEY.
  • TikTok: Validates timestamped webhook signatures against registered secret tokens.

Scheme 4: NextAuth v5 JWT Session (/api/admin/*, /api/user/*)​

Used for customer dashboard operations and administrative management:

  • Transport: Encrypted HTTP-only, SameSite cookie (authjs.session-token).
  • Claims: Encodes user ID, email, role (super_admin, admin, user), and custom expiration times.
  • Route Guards: Server helpers (requireAdmin(), requireSuperAdmin(), requireAuth()) verify claims prior to data mutation.

Scheme 5: OpenAPI Swagger Password Gate (/api/docs)​

To shield internal API schemas from automated reconnaissance while allowing partner developers access:

  • Authentication Route: POST /api/docs/auth
  • Verification: Submissions are bcrypt-compared against SWAGGER_DOCS_PASSWORD_HASH. Successful validation yields a temporary signed JWT granting access to /api/docs and /api/docs/openapi.json.

3. Standardized Response & Error Envelopes​

All API routes emit structured JSON envelopes following consistent schemas.

Successful Response Format​

{
  "success": true,
  "data": {
    "quoteId": "HT-2026-99214",
    "status": "received",
    "createdAt": "2026-11-03T08:30:00.000Z"
  },
  "message": "Quote completed and queued for underwriting assignment."
}

Standardized Error Format (RFC 7807 Inspired)​

{
  "success": false,
  "error": "Validation failed on one or more payload fields.",
  "code": "VALIDATION_ERROR",
  "details": [
    {
      "field": "vinNumber",
      "message": "VIN must be exactly 17 alphanumeric characters."
    }
  ]
}

Common HTTP Status Codes​

  • 200 OK: Request succeeded; data returned.
  • 201 Created: Resource successfully created in MongoDB (e.g. quote draft, claim report).
  • 400 Bad Request: Malformed JSON or failed Zod schema validation.
  • 401 Unauthorized: Missing or invalid session token or HMAC signature.
  • 403 Forbidden: Authenticated user lacks required RBAC privileges (e.g. standard user calling admin action).
  • 404 Not Found: Resource does not exist, or security cloaking invoked.
  • 422 Unprocessable Entity: Semantic business validation failure.
  • 429 Too Many Requests: Exceeded sliding-window rate limit quota.
  • 500 Internal Server Error: Unhandled server exception (sanitized in production).
  • 503 Service Unavailable: MongoDB connection pool exhaustion or downstream CRM outage.

4. Complete Endpoint Catalog​

For full request/response schemas, sample curl snippets, and payload validation rules for all 39 platform endpoints, refer to the exhaustive API Endpoints Reference.