Skip to content

Hub API Reference

The CyberEco Hub exposes a REST API for authentication, data export, privacy management, and security reporting. All endpoints are served under the /api/ path prefix.

Authentication

Most API endpoints require an active session via the cybereco-auth-token httpOnly cookie. This cookie is set during the login flow (see Auth Flow) and contains the user's Firebase UID.

Endpoints that require authentication will return a 401 Unauthorized response if the cookie is missing or empty.

CSRF Protection

State-changing requests (POST, PUT, DELETE, PATCH) must include an X-CSRF-Token header matching the cybereco-csrf-token cookie value. See Middleware for details.

Exempt endpoints: /api/auth/login, /api/auth/set-cookie, /api/csp-report.

Endpoint Summary

Method Endpoint Auth Description
POST /api/auth/login No Authenticate with email/password
POST /api/auth/set-cookie No Set auth cookie after client-side Firebase login
POST /api/auth/generate-token Yes Generate SSO token for cross-app navigation
POST /api/auth/refresh Yes Refresh auth cookie expiry
DELETE /api/auth/refresh Yes Clear auth cookie (sign out)
GET /api/export Yes Get available export options
POST /api/export Yes Export user data (JSON or CSV)
GET /api/privacy/settings Yes Get privacy settings
PUT /api/privacy/settings Yes Update privacy settings
GET /api/privacy/consent Yes Get consent records
POST /api/privacy/consent Yes Record a consent decision
POST /api/csp-report No Receive CSP violation reports

Interactive API Documentation

Error Format

All error responses follow a consistent JSON format:

{
  "error": "Human-readable error message"
}

Common HTTP status codes:

Status Meaning
200 Success
204 Success (no content)
400 Bad request (missing fields, invalid input)
401 Unauthorized (missing or invalid auth cookie)
403 Forbidden (CSRF mismatch, origin not allowed)
429 Too many requests (rate limited by Firebase)
500 Internal server error
  • Auth Flow -- How the auth cookie is established and refreshed
  • Middleware -- CSRF protection, CORS, and security headers
  • Hub Overview -- Architecture and technology stack