Authentication and API Client

The MATIH API client architecture is built on the native Fetch API with httpOnly cookie authentication, CSRF protection, automatic retries with exponential backoff, configurable timeouts, and unified pagination normalization across Java (Spring Boot) and Python (FastAPI) backends. The base ApiClient class at frontend/shared/src/api/client.ts serves as the foundation for 16 domain-specific service clients.

Base API Client

Configuration

interface ApiConfig {
  baseUrl: string;
  tenantId: string;
  userId?: string;
  accessToken?: string;           // @deprecated - use httpOnly cookies
  onUnauthorized?: () => void;
  withCredentials?: boolean;       // Default: true
  timeout?: number;                // Default: 30000ms
  retries?: number;                // Default: 2
}

Authentication Model

The API client uses httpOnly cookies for authentication. Tokens are set by the backend and sent automatically with credentials: 'include'. CSRF protection is provided via the X-XSRF-TOKEN header extracted from a cookie set by the backend.

Retry Strategy

Automatic retries with exponential backoff for 5xx and 429 responses:

Unified Pagination

The normalizePagedResponse function handles pagination differences between Spring Boot (content/totalElements) and FastAPI (items/total) backends, plus cursor-based pagination.

Service Client Modules

Singleton Pattern

let apiClientInstance: ApiClient | null = null;
 
export function initializeApiClient(config: ApiConfig): ApiClient {
  apiClientInstance = new ApiClient(config);
  return apiClientInstance;
}
 
export function getApiClient(): ApiClient {
  if (!apiClientInstance) {
    throw new Error('API client not initialized.');
  }
  return apiClientInstance;
}

For detailed API client internals, see Shared Library - API Clients.